tablet/amethyst
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
ff112713f9
amethyst/assets/indices/contentIndex.json
Ben Cuan ff112713f9 initial commit: combine book with quartz
2023-01-01 23:41:14 +00:00

266 lines
137 KiB
JSON
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

{
"/": {
"title": "🪴 Quartz 3.",
"content": "\nHost your second brain and [digital garden](https://jzhao.xyz/posts/networked-thought) for free. Quartz features\n\n1. Extremely fast natural-language [[notes/search]]\n2. Customizable and hackable design based on [Hugo](https://gohugo.io/)\n3. Automatically generated backlinks, link previews, and local graph\n4. Built-in [[notes/CJK + Latex Support (测试) | CJK + Latex Support]] and [[notes/callouts | Admonition-style callouts]]\n5. Support for both Markdown Links and Wikilinks\n\nCheck out some of the [amazing gardens that community members](notes/showcase.md) have published with Quartz or read about [why I made Quartz](notes/philosophy.md) to begin with.\n\n## Get Started\n\u003e 📚 Step 1: [Setup your own digital garden using Quartz](notes/setup.md)\n\nReturning user? Figure out how to [[notes/updating|update]] your existing Quartz garden.\n\nIf you prefer browsing the contents of this site through a list instead of a graph, you see a list of all [setup-related notes](/tags/setup).\n\n### Troubleshooting\n- 🚧 [Troubleshooting and FAQ](notes/troubleshooting.md)\n- 🐛 [Submit an Issue](https://github.com/jackyzha0/quartz/issues)\n- 👀 [Discord Community](https://discord.gg/cRFFHYye7t)\n\n[[notes/foo]] [[notes/foo/footest]]",
"lastmodified": "2022-12-31T02:09:59.91496047Z",
"tags": null
},
"/docs/example/": {
"title": "Example Site",
"content": "\n# Introduction\n\n## Ferre hinnitibus erat accipitrem dixi Troiae tollens\n\nLorem markdownum, a quoque nutu est *quodcumque mandasset* veluti. Passim\ninportuna totidemque nympha fert; repetens pendent, poenarum guttura sed vacet\nnon, mortali undas. Omnis pharetramque gramen portentificisque membris servatum\nnovabis fallit de nubibus atque silvas mihi. **Dixit repetitaque Quid**; verrit\nlonga; sententia [mandat](http://pastor-ad.io/questussilvas) quascumque nescio\nsolebat [litore](http://lacrimas-ab.net/); noctes. *Hostem haerentem* circuit\n[plenaque tamen](http://www.sine.io/in).\n\n- Pedum ne indigenae finire invergens carpebat\n- Velit posses summoque\n- De fumos illa foret\n\n## Est simul fameque tauri qua ad\n\nLocum nullus nisi vomentes. Ab Persea sermone vela, miratur aratro; eandem\nArgolicas gener.\n\n## Me sol\n\nNec dis certa fuit socer, Nonacria **dies** manet tacitaque sibi? Sucis est\niactata Castrumque iudex, et iactato quoque terraeque es tandem et maternos\nvittis. Lumina litus bene poenamque animos callem ne tuas in leones illam dea\ncadunt genus, et pleno nunc in quod. Anumque crescentesque sanguinis\n[progenies](http://www.late.net/alimentavirides) nuribus rustica tinguet. Pater\nomnes liquido creditis noctem.\n\n if (mirrored(icmp_dvd_pim, 3, smbMirroredHard) != lion(clickImportQueue,\n viralItunesBalancing, bankruptcy_file_pptp)) {\n file += ip_cybercrime_suffix;\n }\n if (runtimeSmartRom == netMarketingWord) {\n virusBalancingWin *= scriptPromptBespoke + raster(post_drive,\n windowsSli);\n cd = address_hertz_trojan;\n soap_ccd.pcbServerGigahertz(asp_hardware_isa, offlinePeopleware, nui);\n } else {\n megabyte.api = modem_flowchart - web + syntaxHalftoneAddress;\n }\n if (3 \u003c mebibyteNetworkAnimated) {\n pharming_regular_error *= jsp_ribbon + algorithm * recycleMediaKindle(\n dvrSyntax, cdma);\n adf_sla *= hoverCropDrive;\n templateNtfs = -1 - vertical;\n } else {\n expressionCompressionVariable.bootMulti = white_eup_javascript(\n table_suffix);\n guidPpiPram.tracerouteLinux += rtfTerabyteQuicktime(1,\n managementRosetta(webcamActivex), 740874);\n }\n var virusTweetSsl = nullGigo;\n\n## Trepident sitimque\n\nSentiet et ferali errorem fessam, coercet superbus, Ascaniumque in pennis\nmediis; dolor? Vidit imi **Aeacon** perfida propositos adde, tua Somni Fluctibus\nerrante lustrat non.\n\nTamen inde, vos videt e flammis Scythica parantem rupisque pectora umbras. Haec\nficta canistris repercusso simul ego aris Dixit! Esse Fama trepidare hunc\ncrescendo vigor ululasse vertice *exspatiantur* celer tepidique petita aversata\noculis iussa est me ferro.\n",
"lastmodified": "2022-12-31T01:56:53.430566995Z",
"tags": null
},
"/docs/example/collapsed/": {
"title": "",
"content": "",
"lastmodified": "2022-12-31T01:56:53.430566995Z",
"tags": null
},
"/docs/example/collapsed/3rd-level/": {
"title": "",
"content": "# 3rd Level of Menu\n\nNefas discordemque domino montes numen tum humili nexilibusque exit, Iove. Quae\nmiror esse, scelerisque Melaneus viribus. Miseri laurus. Hoc est proposita me\nante aliquid, aura inponere candidioribus quidque accendit bella, sumpta.\nIntravit quam erat figentem hunc, motus de fontes parvo tempestate.\n\n iscsi_virus = pitch(json_in_on(eupViral),\n northbridge_services_troubleshooting, personal(\n firmware_rw.trash_rw_crm.device(interactive_gopher_personal,\n software, -1), megabit, ergonomicsSoftware(cmyk_usb_panel,\n mips_whitelist_duplex, cpa)));\n if (5) {\n managementNetwork += dma - boolean;\n kilohertz_token = 2;\n honeypot_affiliate_ergonomics = fiber;\n }\n mouseNorthbridge = byte(nybble_xmp_modem.horse_subnet(\n analogThroughputService * graphicPoint, drop(daw_bit, dnsIntranet),\n gateway_ospf), repository.domain_key.mouse(serverData(fileNetwork,\n trim_duplex_file), cellTapeDirect, token_tooltip_mashup(\n ripcordingMashup)));\n module_it = honeypot_driver(client_cold_dvr(593902, ripping_frequency) +\n coreLog.joystick(componentUdpLink), windows_expansion_touchscreen);\n bashGigabit.external.reality(2, server_hardware_codec.flops.ebookSampling(\n ciscNavigationBacklink, table + cleanDriver), indexProtocolIsp);\n",
"lastmodified": "2022-12-31T01:56:53.430566995Z",
"tags": null
},
"/docs/example/collapsed/3rd-level/4th-level": {
"title": "",
"content": "# 4th Level of Menu\n\n## Caesorum illa tu sentit micat vestes papyriferi\n\nInde aderam facti; Theseus vis de tauri illa peream. Oculos **uberaque** non\nregisque vobis cursuque, opus venit quam vulnera. Et maiora necemque, lege modo;\ngestanda nitidi, vero? Dum ne pectoraque testantur.\n\nVenasque repulsa Samos qui, exspectatum eram animosque hinc, [aut\nmanes](http://www.creveratnon.net/apricaaetheriis), Assyrii. Cupiens auctoribus\npariter rubet, profana magni super nocens. Vos ius sibilat inpar turba visae\niusto! Sedes ante dum superest **extrema**.\n",
"lastmodified": "2022-12-31T01:56:53.430566995Z",
"tags": null
},
"/docs/example/hidden": {
"title": "",
"content": "\n# This page is hidden in menu\n\n# Quondam non pater est dignior ille Eurotas\n\n## Latent te facies\n\nLorem markdownum arma ignoscas vocavit quoque ille texit mandata mentis ultimus,\nfrementes, qui in vel. Hippotades Peleus [pennas\nconscia](http://gratia.net/tot-qua.php) cuiquam Caeneus quas.\n\n- Pater demittere evincitque reddunt\n- Maxime adhuc pressit huc Danaas quid freta\n- Soror ego\n- Luctus linguam saxa ultroque prior Tatiumque inquit\n- Saepe liquitur subita superata dederat Anius sudor\n\n## Cum honorum Latona\n\nO fallor [in sustinui\niussorum](http://www.spectataharundine.org/aquas-relinquit.html) equidem.\nNymphae operi oris alii fronde parens dumque, in auro ait mox ingenti proxima\niamdudum maius?\n\n reality(burnDocking(apache_nanometer),\n pad.property_data_programming.sectorBrowserPpga(dataMask, 37,\n recycleRup));\n intellectualVaporwareUser += -5 * 4;\n traceroute_key_upnp /= lag_optical(android.smb(thyristorTftp));\n surge_host_golden = mca_compact_device(dual_dpi_opengl, 33,\n commerce_add_ppc);\n if (lun_ipv) {\n verticalExtranet(1, thumbnail_ttl, 3);\n bar_graphics_jpeg(chipset - sector_xmp_beta);\n }\n\n## Fronde cetera dextrae sequens pennis voce muneris\n\nActa cretus diem restet utque; move integer, oscula non inspirat, noctisque\nscelus! Nantemque in suas vobis quamvis, et labori!\n\n var runtimeDiskCompiler = home - array_ad_software;\n if (internic \u003e disk) {\n emoticonLockCron += 37 + bps - 4;\n wan_ansi_honeypot.cardGigaflops = artificialStorageCgi;\n simplex -= downloadAccess;\n }\n var volumeHardeningAndroid = pixel + tftp + onProcessorUnmount;\n sector(memory(firewire + interlaced, wired));",
"lastmodified": "2022-12-31T01:56:53.430566995Z",
"tags": null
},
"/docs/example/table-of-contents/": {
"title": "",
"content": "\n# Ubi loqui\n\n## Mentem genus facietque salire tempus bracchia\n\nLorem markdownum partu paterno Achillem. Habent amne generosi aderant ad pellem\nnec erat sustinet merces columque haec et, dixit minus nutrit accipiam subibis\nsubdidit. Temeraria servatum agros qui sed fulva facta. Primum ultima, dedit,\nsuo quisque linguae medentes fixo: tum petis.\n\n## Rapit vocant si hunc siste adspice\n\nOra precari Patraeque Neptunia, dixit Danae [Cithaeron\narmaque](http://mersis-an.org/litoristum) maxima in **nati Coniugis** templis\nfluidove. Effugit usus nec ingreditur agmen *ac manus* conlato. Nullis vagis\nnequiquam vultibus aliquos altera *suum venis* teneas fretum. Armos [remotis\nhoc](http://tutum.io/me) sine ferrea iuncta quam!\n\n## Locus fuit caecis\n\nNefas discordemque domino montes numen tum humili nexilibusque exit, Iove. Quae\nmiror esse, scelerisque Melaneus viribus. Miseri laurus. Hoc est proposita me\nante aliquid, aura inponere candidioribus quidque accendit bella, sumpta.\nIntravit quam erat figentem hunc, motus de fontes parvo tempestate.\n\n iscsi_virus = pitch(json_in_on(eupViral),\n northbridge_services_troubleshooting, personal(\n firmware_rw.trash_rw_crm.device(interactive_gopher_personal,\n software, -1), megabit, ergonomicsSoftware(cmyk_usb_panel,\n mips_whitelist_duplex, cpa)));\n if (5) {\n managementNetwork += dma - boolean;\n kilohertz_token = 2;\n honeypot_affiliate_ergonomics = fiber;\n }\n mouseNorthbridge = byte(nybble_xmp_modem.horse_subnet(\n analogThroughputService * graphicPoint, drop(daw_bit, dnsIntranet),\n gateway_ospf), repository.domain_key.mouse(serverData(fileNetwork,\n trim_duplex_file), cellTapeDirect, token_tooltip_mashup(\n ripcordingMashup)));\n module_it = honeypot_driver(client_cold_dvr(593902, ripping_frequency) +\n coreLog.joystick(componentUdpLink), windows_expansion_touchscreen);\n bashGigabit.external.reality(2, server_hardware_codec.flops.ebookSampling(\n ciscNavigationBacklink, table + cleanDriver), indexProtocolIsp);\n\n## Placabilis coactis nega ingemuit ignoscat nimia non\n\nFrontis turba. Oculi gravis est Delphice; *inque praedaque* sanguine manu non.\n\n if (ad_api) {\n zif += usb.tiffAvatarRate(subnet, digital_rt) + exploitDrive;\n gigaflops(2 - bluetooth, edi_asp_memory.gopher(queryCursor, laptop),\n panel_point_firmware);\n spyware_bash.statePopApplet = express_netbios_digital(\n insertion_troubleshooting.brouter(recordFolderUs), 65);\n }\n recursionCoreRay = -5;\n if (hub == non) {\n portBoxVirus = soundWeb(recursive_card(rwTechnologyLeopard),\n font_radcab, guidCmsScalable + reciprocalMatrixPim);\n left.bug = screenshot;\n } else {\n tooltipOpacity = raw_process_permalink(webcamFontUser, -1);\n executable_router += tape;\n }\n if (tft) {\n bandwidthWeb *= social_page;\n } else {\n regular += 611883;\n thumbnail /= system_lag_keyboard;\n }\n\n## Caesorum illa tu sentit micat vestes papyriferi\n\nInde aderam facti; Theseus vis de tauri illa peream. Oculos **uberaque** non\nregisque vobis cursuque, opus venit quam vulnera. Et maiora necemque, lege modo;\ngestanda nitidi, vero? Dum ne pectoraque testantur.\n\nVenasque repulsa Samos qui, exspectatum eram animosque hinc, [aut\nmanes](http://www.creveratnon.net/apricaaetheriis), Assyrii. Cupiens auctoribus\npariter rubet, profana magni super nocens. Vos ius sibilat inpar turba visae\niusto! Sedes ante dum superest **extrema**.\n",
"lastmodified": "2022-12-31T01:56:53.430566995Z",
"tags": null
},
"/docs/example/table-of-contents/with-toc": {
"title": "With ToC",
"content": "# Caput vino delphine in tamen vias\n\n## Cognita laeva illo fracta\n\nLorem markdownum pavent auras, surgit nunc cingentibus libet **Laomedonque que**\nest. Pastor [An](http://est.org/ire.aspx) arbor filia foedat, ne [fugit\naliter](http://www.indiciumturbam.org/moramquid.php), per. Helicona illas et\ncallida neptem est *Oresitrophos* caput, dentibus est venit. Tenet reddite\n[famuli](http://www.antro-et.net/) praesentem fortibus, quaeque vis foret si\nfrondes *gelidos* gravidae circumtulit [inpulit armenta\nnativum](http://incurvasustulit.io/illi-virtute.html).\n\n1. Te at cruciabere vides rubentis manebo\n2. Maturuit in praetemptat ruborem ignara postquam habitasse\n3. Subitarum supplevit quoque fontesque venabula spretis modo\n4. Montis tot est mali quasque gravis\n5. Quinquennem domus arsit ipse\n6. Pellem turis pugnabant locavit\n\n## Natus quaerere\n\nPectora et sine mulcere, coniuge dum tincta incurvae. Quis iam; est dextra\nPeneosque, metuis a verba, primo. Illa sed colloque suis: magno: gramen, aera\nexcutiunt concipit.\n\n\u003e Phrygiae petendo suisque extimuit, super, pars quod audet! Turba negarem.\n\u003e Fuerat attonitus; et dextra retinet sidera ulnas undas instimulat vacuae\n\u003e generis? *Agnus* dabat et ignotis dextera, sic tibi pacis **feriente at mora**\n\u003e euhoeque *comites hostem* vestras Phineus. Vultuque sanguine dominoque [metuit\n\u003e risi](http://iuvat.org/eundem.php) fama vergit summaque meus clarissimus\n\u003e artesque tinguebat successor nominis cervice caelicolae.\n\n## Limitibus misere sit\n\nAurea non fata repertis praerupit feruntur simul, meae hosti lentaque *citius\nlevibus*, cum sede dixit, Phaethon texta. *Albentibus summos* multifidasque\niungitur loquendi an pectore, mihi ursaque omnia adfata, aeno parvumque in animi\nperlucentes. Epytus agis ait vixque clamat ornum adversam spondet, quid sceptra\nipsum **est**. Reseret nec; saeva suo passu debentia linguam terga et aures et\ncervix [de](http://www.amnem.io/pervenit.aspx) ubera. Coercet gelidumque manus,\ndoluit volvitur induta?\n\n## Enim sua\n\nIuvenilior filia inlustre templa quidem herbis permittat trahens huic. In\ncruribus proceres sole crescitque *fata*, quos quos; merui maris se non tamen\nin, mea.\n\n## Germana aves pignus tecta\n\nMortalia rudibusque caelum cognosceret tantum aquis redito felicior texit, nec,\naris parvo acre. Me parum contulerant multi tenentem, gratissime suis; vultum tu\noccupat deficeret corpora, sonum. E Actaea inplevit Phinea concepit nomenque\npotest sanguine captam nulla et, in duxisses campis non; mercede. Dicere cur\nLeucothoen obitum?\n\nPostibus mittam est *nubibus principium pluma*, exsecratur facta et. Iunge\nMnemonidas pallamque pars; vere restitit alis flumina quae **quoque**, est\nignara infestus Pyrrha. Di ducis terris maculatum At sede praemia manes\nnullaque!\n",
"lastmodified": "2022-12-31T01:56:53.430566995Z",
"tags": null
},
"/docs/example/table-of-contents/without-toc": {
"title": "Without ToC",
"content": "\n# At me ipso nepotibus nunc celebratior genus\n\n## Tanto oblite\n\nLorem markdownum pectora novis patenti igne sua opus aurae feras materiaque\nillic demersit imago et aristas questaque posset. Vomit quoque suo inhaesuro\nclara. Esse cumque, per referri triste. Ut exponit solisque communis in tendens\nvincetis agisque iamque huic bene ante vetat omina Thebae rates. Aeacus servat\nadmonitu concidit, ad resimas vultus et rugas vultu **dignamque** Siphnon.\n\nQuam iugulum regia simulacra, plus meruit humo pecorumque haesit, ab discedunt\ndixit: ritu pharetramque. Exul Laurenti orantem modo, per densum missisque labor\nmanibus non colla unum, obiectat. Tu pervia collo, fessus quae Cretenque Myconon\ncrate! Tegumenque quae invisi sudore per vocari quaque plus ventis fluidos. Nodo\nperque, fugisse pectora sorores.\n\n## Summe promissa supple vadit lenius\n\nQuibus largis latebris aethera versato est, ait sentiat faciemque. Aequata alis\nnec Caeneus exululat inclite corpus est, ire **tibi** ostendens et tibi. Rigent\net vires dique possent lumina; **eadem** dixit poma funeribus paret et felix\nreddebant ventis utile lignum.\n\n1. Remansit notam Stygia feroxque\n2. Et dabit materna\n3. Vipereas Phrygiaeque umbram sollicito cruore conlucere suus\n4. Quarum Elis corniger\n5. Nec ieiunia dixit\n\nVertitur mos ortu ramosam contudit dumque; placabat ac lumen. Coniunx Amoris\nspatium poenamque cavernis Thebae Pleiadasque ponunt, rapiare cum quae parum\nnimium rima.\n\n## Quidem resupinus inducto solebat una facinus quae\n\nCredulitas iniqua praepetibus paruit prospexit, voce poena, sub rupit sinuatur,\nquin suum ventorumque arcadiae priori. Soporiferam erat formamque, fecit,\ninvergens, nymphae mutat fessas ait finge.\n\n1. Baculum mandataque ne addere capiti violentior\n2. Altera duas quam hoc ille tenues inquit\n3. Sicula sidereus latrantis domoque ratae polluit comites\n4. Possit oro clausura namque se nunc iuvenisque\n5. Faciem posuit\n6. Quodque cum ponunt novercae nata vestrae aratra\n\nIte extrema Phrygiis, patre dentibus, tonso perculit, enim blanda, manibus fide\nquos caput armis, posse! Nocendo fas Alcyonae lacertis structa ferarum manus\nfulmen dubius, saxa caelum effuge extremis fixum tumor adfecit **bella**,\npotentes? Dum nec insidiosa tempora tegit\n[spirarunt](http://mihiferre.net/iuvenes-peto.html). Per lupi pars foliis,\nporreximus humum negant sunt subposuere Sidone steterant auro. Memoraverit sine:\nferrum idem Orion caelum heres gerebat fixis?\n",
"lastmodified": "2022-12-31T01:56:53.430566995Z",
"tags": null
},
"/docs/shortcodes/": {
"title": "",
"content": "",
"lastmodified": "2022-12-31T01:56:53.430566995Z",
"tags": null
},
"/docs/shortcodes/buttons": {
"title": "",
"content": "# Buttons\n\nButtons are styled links that can lead to local page or external link.\n\n## Example\n\n```tpl\n{{\u003c/* button relref=\"/\" [class=\"...\"] */\u003e}}Get Home{{\u003c/* /button */\u003e}}\n{{\u003c/* button href=\"https://github.com/alex-shpak/hugo-book\" */\u003e}}Contribute{{\u003c/* /button */\u003e}}\n```\n\n{{\u003c button relref=\"/\" \u003e}}Get Home{{\u003c /button \u003e}}\n{{\u003c button href=\"https://github.com/alex-shpak/hugo-book\" \u003e}}Contribute{{\u003c /button \u003e}}\n",
"lastmodified": "2022-12-31T01:56:53.430566995Z",
"tags": null
},
"/docs/shortcodes/columns": {
"title": "",
"content": "# Columns\n\nColumns help organize shorter pieces of content horizontally for readability.\n\n\n```html\n{{\u003c/* columns */\u003e}} \u003c!-- begin columns block --\u003e\n# Left Content\nLorem markdownum insigne...\n\n\u003c---\u003e \u003c!-- magic separator, between columns --\u003e\n\n# Mid Content\nLorem markdownum insigne...\n\n\u003c---\u003e \u003c!-- magic separator, between columns --\u003e\n\n# Right Content\nLorem markdownum insigne...\n{{\u003c/* /columns */\u003e}}\n```\n\n## Example\n\n{{\u003c columns \u003e}}\n## Left Content\nLorem markdownum insigne. Olympo signis Delphis! Retexi Nereius nova develat\nstringit, frustra Saturnius uteroque inter! Oculis non ritibus Telethusa\nprotulit, sed sed aere valvis inhaesuro Pallas animam: qui _quid_, ignes.\nMiseratus fonte Ditis conubia.\n\n\u003c---\u003e\n\n## Mid Content\nLorem markdownum insigne. Olympo signis Delphis! Retexi Nereius nova develat\nstringit, frustra Saturnius uteroque inter!\n\n\u003c---\u003e\n\n## Right Content\nLorem markdownum insigne. Olympo signis Delphis! Retexi Nereius nova develat\nstringit, frustra Saturnius uteroque inter! Oculis non ritibus Telethusa\nprotulit, sed sed aere valvis inhaesuro Pallas animam: qui _quid_, ignes.\nMiseratus fonte Ditis conubia.\n{{\u003c /columns \u003e}}\n",
"lastmodified": "2022-12-31T01:56:53.430566995Z",
"tags": null
},
"/docs/shortcodes/details": {
"title": "",
"content": "# Details\n\nDetails shortcode is a helper for `details` html5 element. It is going to replace `expand` shortcode.\n\n## Example\n```tpl\n{{\u003c/* details \"Title\" [open] */\u003e}}\n## Markdown content\nLorem markdownum insigne...\n{{\u003c/* /details */\u003e}}\n```\n```tpl\n{{\u003c/* details title=\"Title\" open=true */\u003e}}\n## Markdown content\nLorem markdownum insigne...\n{{\u003c/* /details */\u003e}}\n```\n\n{{\u003c details \"Title\" open \u003e}}\n## Markdown content\nLorem markdownum insigne...\n{{\u003c /details \u003e}}\n",
"lastmodified": "2022-12-31T01:56:53.430566995Z",
"tags": null
},
"/docs/shortcodes/expand": {
"title": "",
"content": "# Expand\n\nExpand shortcode can help to decrease clutter on screen by hiding part of text. Expand content by clicking on it.\n\n## Example\n### Default\n\n```tpl\n{{\u003c/* expand */\u003e}}\n## Markdown content\nLorem markdownum insigne...\n{{\u003c/* /expand */\u003e}}\n```\n\n{{\u003c expand \u003e}}\n## Markdown content\nLorem markdownum insigne...\n{{\u003c /expand \u003e}}\n\n### With Custom Label\n\n```tpl\n{{\u003c/* expand \"Custom Label\" \"...\" */\u003e}}\n## Markdown content\nLorem markdownum insigne...\n{{\u003c/* /expand */\u003e}}\n```\n\n{{\u003c expand \"Custom Label\" \"...\" \u003e}}\n## Markdown content\nLorem markdownum insigne. Olympo signis Delphis! Retexi Nereius nova develat\nstringit, frustra Saturnius uteroque inter! Oculis non ritibus Telethusa\nprotulit, sed sed aere valvis inhaesuro Pallas animam: qui _quid_, ignes.\nMiseratus fonte Ditis conubia.\n{{\u003c /expand \u003e}}\n",
"lastmodified": "2022-12-31T01:56:53.430566995Z",
"tags": null
},
"/docs/shortcodes/hints": {
"title": "",
"content": "# Hints\n\nHint shortcode can be used as hint/alerts/notification block. \nThere are 3 colors to choose: `info`, `warning` and `danger`.\n\n```tpl\n{{\u003c/* hint [info|warning|danger] */\u003e}}\n**Markdown content** \nLorem markdownum insigne. Olympo signis Delphis! Retexi Nereius nova develat\nstringit, frustra Saturnius uteroque inter! Oculis non ritibus Telethusa\n{{\u003c/* /hint */\u003e}}\n```\n\n## Example\n\n{{\u003c hint info \u003e}}\n**Markdown content** \nLorem markdownum insigne. Olympo signis Delphis! Retexi Nereius nova develat\nstringit, frustra Saturnius uteroque inter! Oculis non ritibus Telethusa\n{{\u003c /hint \u003e}}\n\n{{\u003c hint warning \u003e}}\n**Markdown content** \nLorem markdownum insigne. Olympo signis Delphis! Retexi Nereius nova develat\nstringit, frustra Saturnius uteroque inter! Oculis non ritibus Telethusa\n{{\u003c /hint \u003e}}\n\n{{\u003c hint danger \u003e}}\n**Markdown content** \nLorem markdownum insigne. Olympo signis Delphis! Retexi Nereius nova develat\nstringit, frustra Saturnius uteroque inter! Oculis non ritibus Telethusa\n{{\u003c /hint \u003e}}\n",
"lastmodified": "2022-12-31T01:56:53.430566995Z",
"tags": null
},
"/docs/shortcodes/katex": {
"title": "",
"content": "# KaTeX\n\nKaTeX shortcode let you render math typesetting in markdown document. See [KaTeX](https://katex.org/)\n\n## Example\n{{\u003c columns \u003e}}\n\n```latex\n{{\u003c/*/* katex [display] [class=\"text-center\"] */*/\u003e}}\nf(x) = \\int_{-\\infty}^\\infty\\hat f(\\xi)\\,e^{2 \\pi i \\xi x}\\,d\\xi\n{{\u003c/*/* /katex */*/\u003e}}\n```\n\n\u003c---\u003e\n\n{{\u003c katex display \u003e}}\nf(x) = \\int_{-\\infty}^\\infty\\hat f(\\xi)\\,e^{2 \\pi i \\xi x}\\,d\\xi\n{{\u003c /katex \u003e}}\n\n{{\u003c /columns \u003e}}\n\n## Display Mode Example\n\nHere is some inline example: {{\u003c katex \u003e}}\\pi(x){{\u003c /katex \u003e}}, rendered in the same line. And below is `display` example, having `display: block`\n{{\u003c katex display \u003e}}\nf(x) = \\int_{-\\infty}^\\infty\\hat f(\\xi)\\,e^{2 \\pi i \\xi x}\\,d\\xi\n{{\u003c /katex \u003e}}\nText continues here.\n",
"lastmodified": "2022-12-31T01:56:53.430566995Z",
"tags": null
},
"/docs/shortcodes/mermaid": {
"title": "",
"content": "# Mermaid Chart\n\n[MermaidJS](https://mermaid-js.github.io/) is library for generating svg charts and diagrams from text.\n\n{{\u003c hint info \u003e}}\n**Override Mermaid Initialization Config**\n\nTo override the [initialization config](https://mermaid-js.github.io/mermaid/#/Setup) for Mermaid,\ncreate a `mermaid.json` file in your `assets` folder!\n{{\u003c /hint \u003e}}\n\n## Example\n\n{{\u003c columns \u003e}}\n```tpl\n{{\u003c/*/* mermaid [class=\"text-center\"]*/*/\u003e}}\nstateDiagram-v2\n State1: The state with a note\n note right of State1\n Important information! You can write\n notes.\n end note\n State1 --\u003e State2\n note left of State2 : This is the note to the left.\n{{\u003c/*/* /mermaid */*/\u003e}}\n```\n\n\u003c---\u003e\n\n{{\u003c mermaid \u003e}}\nstateDiagram-v2\n State1: The state with a note\n note right of State1\n Important information! You can write\n notes.\n end note\n State1 --\u003e State2\n note left of State2 : This is the note to the left.\n{{\u003c /mermaid \u003e}}\n\n{{\u003c /columns \u003e}}\n",
"lastmodified": "2022-12-31T01:56:53.430566995Z",
"tags": null
},
"/docs/shortcodes/section/": {
"title": "",
"content": "\n# Section\n\nSection renders pages in section as definition list, using title and description.\n\n## Example\n\n```tpl\n{{\u003c/* section */\u003e}}\n```\n\n{{\u003csection\u003e}}\n",
"lastmodified": "2022-12-31T01:56:53.430566995Z",
"tags": null
},
"/docs/shortcodes/section/first-page": {
"title": "",
"content": "# First page\n\nLorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. \n\n\u003c!--more--\u003e\nDuis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.\n",
"lastmodified": "2022-12-31T01:56:53.430566995Z",
"tags": null
},
"/docs/shortcodes/section/second-page": {
"title": "",
"content": "# Second Page\nLorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n\n\u003c!--more--\u003e\nDuis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.\n\n",
"lastmodified": "2022-12-31T01:56:53.430566995Z",
"tags": null
},
"/docs/shortcodes/tabs": {
"title": "",
"content": "# Tabs\n\nTabs let you organize content by context, for example installation instructions for each supported platform.\n\n```tpl\n{{\u003c/* tabs \"uniqueid\" */\u003e}}\n{{\u003c/* tab \"MacOS\" */\u003e}} # MacOS Content {{\u003c/* /tab */\u003e}}\n{{\u003c/* tab \"Linux\" */\u003e}} # Linux Content {{\u003c/* /tab */\u003e}}\n{{\u003c/* tab \"Windows\" */\u003e}} # Windows Content {{\u003c/* /tab */\u003e}}\n{{\u003c/* /tabs */\u003e}}\n```\n\n## Example\n\n{{\u003c tabs \"uniqueid\" \u003e}}\n{{\u003c tab \"MacOS\" \u003e}}\n# MacOS\n\nThis is tab **MacOS** content.\n\nLorem markdownum insigne. Olympo signis Delphis! Retexi Nereius nova develat\nstringit, frustra Saturnius uteroque inter! Oculis non ritibus Telethusa\nprotulit, sed sed aere valvis inhaesuro Pallas animam: qui _quid_, ignes.\nMiseratus fonte Ditis conubia.\n{{\u003c /tab \u003e}}\n\n{{\u003c tab \"Linux\" \u003e}}\n\n# Linux\n\nThis is tab **Linux** content.\n\nLorem markdownum insigne. Olympo signis Delphis! Retexi Nereius nova develat\nstringit, frustra Saturnius uteroque inter! Oculis non ritibus Telethusa\nprotulit, sed sed aere valvis inhaesuro Pallas animam: qui _quid_, ignes.\nMiseratus fonte Ditis conubia.\n{{\u003c /tab \u003e}}\n\n{{\u003c tab \"Windows\" \u003e}}\n\n# Windows\n\nThis is tab **Windows** content.\n\nLorem markdownum insigne. Olympo signis Delphis! Retexi Nereius nova develat\nstringit, frustra Saturnius uteroque inter! Oculis non ritibus Telethusa\nprotulit, sed sed aere valvis inhaesuro Pallas animam: qui _quid_, ignes.\nMiseratus fonte Ditis conubia.\n{{\u003c /tab \u003e}}\n{{\u003c /tabs \u003e}}\n",
"lastmodified": "2022-12-31T01:56:53.430566995Z",
"tags": null
},
"/menu": {
"title": "",
"content": "\n- [**Example Site**]({{\u003c relref \"/docs/example\" \u003e}})\n- [Table of Contents]({{\u003c relref \"/docs/example/table-of-contents\" \u003e}})\n - [With ToC]({{\u003c relref \"/docs/example/table-of-contents/with-toc\" \u003e}})\n - [Without ToC]({{\u003c relref \"/docs/example/table-of-contents/without-toc\" \u003e}})\n- [Collapsed]({{\u003c relref \"/docs/example/collapsed\" \u003e}})\n - [3rd]({{\u003c relref \"/docs/example/collapsed/3rd-level\" \u003e}})\n - [4th]({{\u003c relref \"/docs/example/collapsed/3rd-level/4th-level\" \u003e}})\n\u003cbr /\u003e\n\n- **Shortcodes**\n- [Buttons]({{\u003c relref \"/docs/shortcodes/buttons\" \u003e}})\n- [Columns]({{\u003c relref \"/docs/shortcodes/columns\" \u003e}})\n- [Expand]({{\u003c relref \"/docs/shortcodes/expand\" \u003e}})\n- [Hints]({{\u003c relref \"/docs/shortcodes/hints\" \u003e}})\n- [KaTex]({{\u003c relref \"/docs/shortcodes/katex\" \u003e}})\n- [Mermaid]({{\u003c relref \"/docs/shortcodes/mermaid\" \u003e}})\n- [Tabs]({{\u003c relref \"/docs/shortcodes/tabs\" \u003e}})\n\u003cbr /\u003e\n",
"lastmodified": "2022-12-31T01:56:53.430566995Z",
"tags": null
},
"/notes/": {
"title": "Test Notes",
"content": "\n# Hello World",
"lastmodified": "2022-12-31T08:24:36.270068358Z",
"tags": null
},
"/notes/CJK-+-Latex-Support-%E6%B5%8B%E8%AF%95": {
"title": "CJK + Latex Support (测试)",
"content": "\n## Chinese, Japanese, Korean Support\n几乎在我们意识到之前，我们已经离开了地面。\n\n우리가 그것을 알기도 전에 우리는 땅을 떠났습니다.\n\n私たちがそれを知るほぼ前に、私たちは地面を離れていました。\n\n## Latex\n\nBlock math works with two dollar signs `$$...$$`\n\n$$f(x) = \\int_{-\\infty}^\\infty\n f\\hat(\\xi),e^{2 \\pi i \\xi x}\n \\,d\\xi$$\n\t\nInline math also works with single dollar signs `$...$`. For example, Euler's identity but inline: $e^{i\\pi} = -1$\n\nAligned equations work quite well:\n\n$$\n\\begin{aligned}\na \u0026= b + c \\\\ \u0026= e + f \\\\\n\\end{aligned}\n$$\n\nAnd matrices\n\n$$\n\\begin{bmatrix}\n1 \u0026 2 \u0026 3 \\\\\na \u0026 b \u0026 c\n\\end{bmatrix}\n$$\n\n## RTL\nMore information on configuring RTL languages like Arabic in the [config](notes/config.md) page.\n",
"lastmodified": "2022-12-31T02:53:43.340377422Z",
"tags": null
},
"/notes/callouts": {
"title": "Callouts",
"content": "\n## Callout support\n\nQuartz supports the same Admonition-callout syntax as Obsidian.\n\nThis includes\n- 12 Distinct callout types (each with several aliases)\n- Collapsable callouts\n\nSee [documentation on supported types and syntax here](https://help.obsidian.md/How+to/Use+callouts#Types).\n\n## Showcase\n\n\u003e [!EXAMPLE] Examples\n\u003e\n\u003e Aliases: example\n\n\u003e [!note] Notes\n\u003e\n\u003e Aliases: note\n\n\u003e [!abstract] Summaries \n\u003e\n\u003e Aliases: abstract, summary, tldr\n\n\u003e [!info] Info \n\u003e\n\u003e Aliases: info, todo\n\n\u003e [!tip] Hint \n\u003e\n\u003e Aliases: tip, hint, important\n\n\u003e [!success] Success \n\u003e\n\u003e Aliases: success, check, done\n\n\u003e [!question] Question \n\u003e\n\u003e Aliases: question, help, faq\n\n\u003e [!warning] Warning \n\u003e\n\u003e Aliases: warning, caution, attention\n\n\u003e [!failure] Failure \n\u003e\n\u003e Aliases: failure, fail, missing\n\n\u003e [!danger] Error\n\u003e\n\u003e Aliases: danger, error\n\n\u003e [!bug] Bug\n\u003e\n\u003e Aliases: bug\n\n\u003e [!quote] Quote\n\u003e\n\u003e Aliases: quote, cite\n",
"lastmodified": "2022-12-31T02:53:43.340377422Z",
"tags": null
},
"/notes/config": {
"title": "Configuration",
"content": "\n## Configuration\nQuartz is designed to be extremely configurable. You can find the bulk of the configuration scattered throughout the repository depending on how in-depth you'd like to get.\n\nThe majority of configuration can be found under `data/config.yaml`. An annotated example configuration is shown below.\n\n```yaml {title=\"data/config.yaml\"}\n# The name to display in the footer\nname: Jacky Zhao\n\n# whether to globally show the table of contents on each page\n# this can be turned off on a per-page basis by adding this to the\n# front-matter of that note\nenableToc: true\n\n# whether to by-default open or close the table of contents on each page\nopenToc: false\n\n# whether to display on-hover link preview cards\nenableLinkPreview: true\n\n# whether to render titles for code blocks\nenableCodeBlockTitle: true \n\n# whether to render copy buttons for code blocks\nenableCodeBlockCopy: true \n\n# whether to render callouts\nenableCallouts: true\n\n# whether to try to process Latex\nenableLatex: true\n\n# whether to enable single-page-app style rendering\n# this prevents flashes of unstyled content and improves\n# smoothness of Quartz. More info in issue #109 on GitHub\nenableSPA: true\n\n# whether to render a footer\nenableFooter: true\n\n# whether backlinks of pages should show the context in which\n# they were mentioned\nenableContextualBacklinks: true\n\n# whether to show a section of recent notes on the home page\nenableRecentNotes: false\n\n# whether to display an 'edit' button next to the last edited field\n# that links to github\nenableGitHubEdit: true\nGitHubLink: https://github.com/jackyzha0/quartz/tree/hugo/content\n\n# whether to render mermaid diagrams\nenableMermaid: true\n\n# whether to use Operand to power semantic search\n# IMPORTANT: replace this API key with your own if you plan on using\n# Operand search!\nsearch:\n enableSemanticSearch: false\n operandApiKey: \"REPLACE-WITH-YOUR-OPERAND-API-KEY\"\n operandIndexId: \"REPLACE-WITH-YOUR-OPERAND-INDEX-ID\"\n\n# page description used for SEO\ndescription:\n Host your second brain and digital garden for free. Quartz features extremely fast full-text search,\n Wikilink support, backlinks, local graph, tags, and link previews.\n\n# title of the home page (also for SEO)\npage_title:\n \"🪴 Quartz 3.3\"\n\n# links to show in the footer\nlinks:\n - link_name: Twitter\n link: https://twitter.com/_jzhao\n - link_name: Github\n link: https://github.com/jackyzha0\n```\n\n### Code Block Titles\nTo add code block titles with Quartz:\n\n1. Ensure that code block titles are enabled in Quartz's configuration:\n\n ```yaml {title=\"data/config.yaml\", linenos=false}\n enableCodeBlockTitle: true\n ```\n\n2. Add the `title` attribute to the desired [code block\n fence](https://gohugo.io/content-management/syntax-highlighting/#highlighting-in-code-fences):\n\n ```markdown {linenos=false}\n ```yaml {title=\"data/config.yaml\"}\n enableCodeBlockTitle: true # example from step 1\n ```\n ```\n\n**Note** that if `{title=\u003cmy-title\u003e}` is included, and code block titles are not\nenabled, no errors will occur, and the title attribute will be ignored.\n\n### HTML Favicons\nIf you would like to customize the favicons of your Quartz-based website, you \ncan add them to the `data/config.yaml` file. The **default** without any set \n`favicon` key is:\n\n```html {title=\"layouts/partials/head.html\", linenostart=15}\n\u003clink rel=\"shortcut icon\" href=\"icon.png\" type=\"image/png\"\u003e\n```\n\nThe default can be overridden by defining a value to the `favicon` key in your \n`data/config.yaml` file. For example, here is a `List[Dictionary]` example format, which is\nequivalent to the default:\n\n```yaml {title=\"data/config.yaml\", linenos=false}\nfavicon:\n - { rel: \"shortcut icon\", href: \"icon.png\", type: \"image/png\" }\n# - { ... } # Repeat for each additional favicon you want to add\n```\n\nIn this format, the keys are identical to their HTML representations.\n\nIf you plan to add multiple favicons generated by a website (see list below), it\nmay be easier to define it as HTML. Here is an example which appends the \n**Apple touch icon** to Quartz's default favicon:\n\n```yaml {title=\"data/config.yaml\", linenos=false}\nfavicon: |\n \u003clink rel=\"shortcut icon\" href=\"icon.png\" type=\"image/png\"\u003e\n \u003clink rel=\"apple-touch-icon\" sizes=\"180x180\" href=\"/apple-touch-icon.png\"\u003e\n```\n\nThis second favicon will now be used as a web page icon when someone adds your \nwebpage to the home screen of their Apple device. If you are interested in more \ninformation about the current and past standards of favicons, you can read \n[this article](https://www.emergeinteractive.com/insights/detail/the-essentials-of-favicons/).\n\n**Note** that all generated favicon paths, defined by the `href` \nattribute, are relative to the `static/` directory.\n\n### Graph View\nTo customize the Interactive Graph view, you can poke around `data/graphConfig.yaml`.\n\n```yaml {title=\"data/graphConfig.yaml\"}\n# if true, a Global Graph will be shown on home page with full width, no backlink.\n# A different set of Local Graphs will be shown on sub pages.\n# if false, Local Graph will be default on every page as usual\nenableGlobalGraph: false\n\n### Local Graph ###\nlocalGraph:\n # whether automatically generate a legend\n enableLegend: false\n \n # whether to allow dragging nodes in the graph\n enableDrag: true\n \n # whether to allow zooming and panning the graph\n enableZoom: true\n \n # how many neighbours of the current node to show (-1 is all nodes)\n depth: 1\n \n # initial zoom factor of the graph\n scale: 1.2\n \n # how strongly nodes should repel each other\n repelForce: 2\n\n # how strongly should nodes be attracted to the center of gravity\n centerForce: 1\n\n # what the default link length should be\n linkDistance: 1\n \n # how big the node labels should be\n fontSize: 0.6\n \n # scale at which to start fading the labes on nodes\n opacityScale: 3\n\n### Global Graph ###\nglobalGraph:\n\t# same settings as above\n\n### For all graphs ###\n# colour specific nodes path off of their path\npaths:\n - /moc: \"#4388cc\"\n```\n\n\n## Styling\nWant to go even more in-depth? You can add custom CSS styling and change existing colours through editing `assets/styles/custom.scss`. If you'd like to target specific parts of the site, you can add ids and classes to the HTML partials in `/layouts/partials`. \n\n### Partials\nPartials are what dictate what gets rendered to the page. Want to change how pages are styled and structured? You can edit the appropriate layout in `/layouts`.\n\nFor example, the structure of the home page can be edited through `/layouts/index.html`. To customize the footer, you can edit `/layouts/partials/footer.html`\n\nMore info about partials on [Hugo's website.](https://gohugo.io/templates/partials/)\n\nStill having problems? Checkout our [FAQ and Troubleshooting guide](notes/troubleshooting.md).\n\n## Language Support\n[CJK + Latex Support (测试)](notes/CJK%20+%20Latex%20Support%20(测试).md) comes out of the box with Quartz.\n\nWant to support languages that read from right-to-left (like Arabic)? Hugo (and by proxy, Quartz) supports this natively.\n\nFollow the steps [Hugo provides here](https://gohugo.io/content-management/multilingual/#configure-languages) and modify your `config.toml`\n\nFor example:\n\n```toml\ndefaultContentLanguage = 'ar'\n[languages]\n [languages.ar]\n languagedirection = 'rtl'\n title = 'مدونتي'\n weight = 1\n```\n",
"lastmodified": "2022-12-31T02:53:43.344377399Z",
"tags": null
},
"/notes/custom-Domain": {
"title": "Custom Domain",
"content": "\n### Registrar\nThis step is only applicable if you are using a **custom domain**! If you are using a `\u003cYOUR-USERNAME\u003e.github.io` domain, you can skip this step.\n\nFor this last bit to take effect, you also need to create a CNAME record with the DNS provider you register your domain with (i.e. NameCheap, Google Domains).\n\nGitHub has some [documentation on this](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site), but the tldr; is to\n\n1. Go to your forked repository (`github.com/\u003cYOUR-GITHUB-USERNAME\u003e/quartz`) settings page and go to the Pages tab. Under \"Custom domain\", type your custom domain, then click **Save**.\n2. Go to your DNS Provider and create a CNAME record that points from your domain to `\u003cYOUR-GITHUB-USERNAME.github.io.` (yes, with the trailing period).\n\n\t![Example Configuration for Quartz](/notes/images/google-domains.png)*Example Configuration for Quartz*\n3. Wait 30 minutes to an hour for the network changes to kick in.\n4. Done!",
"lastmodified": "2022-12-31T02:53:43.344377399Z",
"tags": null
},
"/notes/docker": {
"title": "Hosting with Docker",
"content": "\nIf you want to host Quartz on a machine without using a webpage hosting service, it may be easier to [install Docker Compose](https://docs.docker.com/compose/install/) and follow the instructions below than to [install Quartz's dependencies manually](notes/preview%20changes.md).\n## Hosting Quartz Locally\nYou can serve Quartz locally at `http://localhost:1313` with the following script, replacing `/path/to/quartz` with the \nactual path to your Quartz folder.\n\ndocker-compose.yml\n```\nservices:\n quartz-hugo:\n image: ghcr.io/jackyzha0/quartz:hugo\n container_name: quartz-hugo\n volumes:\n - /path/to/quartz:/quartz\n ports:\n - 1313:1313\n\n # optional\n environment:\n - HUGO_BIND=0.0.0.0\n - HUGO_BASEURL=http://localhost\n - HUGO_PORT=1313\n - HUGO_APPENDPORT=true\n```\n\nThen run with: `docker-compose up -d` in the same directory as your `docker-compose.yml` file.\n\nWhile the container is running, you can update the `quartz` fork with: `docker exec -it quartz-hugo make update`.\n\n## Exposing Your Container to the Internet\n\n### To Your Public IP Address with Port Forwarding (insecure)\n\nAssuming you are already familiar with [port forwarding](https://en.wikipedia.org/wiki/Port_forwarding) and [setting it up with your router model](https://portforward.com):\n\n1. You should set the environment variable `HUGO_BASEURL=http://your-public-ip` and then start your container.\n2. Set up port forwarding on your router from port `p` to `your-local-ip:1313`.\n3. You should now be able to access Quartz from outside your local network at `http://your-public-ip:p`.\n\nHowever, your HTTP connection will be unencrypted and **this method is not secure**.\n\n### To a Domain using Cloudflare Proxy\n\n1. Port forward 443 (HTTPS) from your machine.\n2. Buy a custom domain (say, `your-domain.com`) from [Cloudflare](https://www.cloudflare.com/products/registrar/). Point a DNS A record from `your-domain.com` to your public IP address and enable the proxy.\n3. Set the environment variables `HUGO_BASEURL=https://your-domain.com`, `HUGO_PORT=443`, and `HUGO_APPENDPORT=false`. Change `1313:1313` to `443:443` for the `ports` in `docker-compose.yml`.\n4. Spin up your Quartz container and enjoy it at `https://your-domain.com`!\n\n### To a Domain using a Reverse Proxy\n\nIf you want to serve more than just Quartz to the internet on this machine (or don't want to use the Cloudflare registrar and proxy), you should follow the steps in the section above (as appropriate) and also set up a reverse proxy, like [Traefik](https://doc.traefik.io/traefik). Be sure to configure your TLS certificates too!\n",
"lastmodified": "2022-12-31T02:53:43.344377399Z",
"tags": null
},
"/notes/editing": {
"title": "Editing Content in Quartz",
"content": "\n## Editing \nQuartz runs on top of [Hugo](https://gohugo.io/) so all notes are written in [Markdown](https://www.markdownguide.org/getting-started/).\n\n### Folder Structure\nHere's a rough overview of what's what.\n\n**All content in your garden can found in the `/content` folder.** To make edits, you can open any of the files and make changes directly and save it. You can organize content into any folder you'd like.\n\n**To edit the main home page, open `/content/_index.md`.**\n\nTo create a link between notes in your garden, just create a normal link using Markdown pointing to the document in question. Please note that **all links should be relative to the root `/content` path**. \n\n```markdown\nFor example, I want to link this current document to `notes/config.md`.\n[A link to the config page](notes/config.md)\n```\n\nSimilarly, you can put local images anywhere in the `/content` folder.\n\n```markdown\nExample image (source is in content/notes/images/example.png)\n![Example Image](/content/notes/images/example.png)\n```\n\nYou can also use wikilinks if that is what you are more comfortable with!\n\n### Front Matter\nHugo is picky when it comes to metadata for files. Make sure that your title is double-quoted and that you have a title defined at the top of your file like so. You can also add tags here as well.\n\n```yaml\n---\ntitle: \"Example Title\"\ntags:\n- example-tag\n---\n\nRest of your content here...\n```\n\n### Obsidian\nI recommend using [Obsidian](http://obsidian.md/) as a way to edit and grow your digital garden. It comes with a really nice editor and graphical interface to preview all of your local files.\n\nThis step is **highly recommended**.\n\n\u003e 🔗 Step 3: [How to setup your Obsidian Vault to work with Quartz](notes/obsidian.md)\n\n## Previewing Changes\nThis step is purely optional and mostly for those who want to see the published version of their digital garden locally before opening it up to the internet. This is *highly recommended* but not required.\n\n\u003e 👀 Step 4: [Preview Quartz Changes](notes/preview%20changes.md)\n\nFor those who like to live life more on the edge, viewing the garden through Obsidian gets you pretty close to the real thing.\n\n## Publishing Changes\nNow that you know the basics of managing your digital garden using Quartz, you can publish it to the internet!\n\n\u003e 🌍 Step 5: [Hosting Quartz online!](notes/hosting.md)\n\nHaving problems? Checkout our [FAQ and Troubleshooting guide](notes/troubleshooting.md).\n",
"lastmodified": "2022-12-31T02:53:43.344377399Z",
"tags": null
},
"/notes/hosting": {
"title": "Deploying Quartz to the Web",
"content": "\n## Hosting on GitHub Pages\nQuartz is designed to be effortless to deploy. If you forked and cloned Quartz directly from the repository, everything should already be good to go! Follow the steps below.\n\n### Enable GitHub Actions\nBy default, GitHub disables workflows from running automatically on Forked Repostories. Head to the 'Actions' tab of your forked repository and Enable Workflows to setup deploying your Quartz site!\n\n![Enable GitHub Actions](notes/images/github-actions.png)*Enable GitHub Actions*\n\n### Enable GitHub Pages\n\nHead to the 'Settings' tab of your forked repository and go to the 'Pages' tab.\n\n1. (IMPORTANT) Set the source to deploy from `master` (and not `hugo`) using `/ (root)`\n2. Set a custom domain here if you have one!\n\n![Enable GitHub Pages](/notes/images/github-pages.png)*Enable GitHub Pages*\n\n### Pushing Changes\nTo see your changes on the internet, we need to push it them to GitHub. Quartz is a `git` repository so updating it is the same workflow as you would follow as if it were just a regular software project.\n\n```shell\n# Navigate to Quartz folder\ncd \u003cpath-to-quartz\u003e\n\n# Commit all changes\ngit add .\ngit commit -m \"message describing changes\"\n\n# Push to GitHub to update site\ngit push origin hugo\n```\n\nNote: we specifically push to the `hugo` branch here. Our GitHub action automatically runs everytime a push to is detected to that branch and then updates the `master` branch for redeployment.\n\n### Setting up the Site\nNow let's get this site up and running. Never hosted a site before? No problem. Have a fancy custom domain you already own or want to subdomain your Quartz? That's easy too.\n\nHere, we take advantage of GitHub's free page hosting to deploy our site. Change `baseURL` in `/config.toml`. \n\nMake sure that your `baseURL` has a trailing `/`!\n\n[Reference `config.toml` here](https://github.com/jackyzha0/quartz/blob/hugo/config.toml)\n\n```toml\nbaseURL = \"https://\u003cYOUR-DOMAIN\u003e/\"\n```\n\nIf you are using this under a subdomain (e.g. `\u003cYOUR-GITHUB-USERNAME\u003e.github.io/quartz`), include the trailing `/`. **You need to do this especially if you are using GitHub!**\n\n```toml\nbaseURL = \"https://\u003cYOUR-GITHUB-USERNAME\u003e.github.io/quartz/\"\n```\n\nChange `cname` in `/.github/workflows/deploy.yaml`. Again, if you don't have a custom domain to use, you can use `\u003cYOUR-USERNAME\u003e.github.io`.\n\nPlease note that the `cname` field should *not* have any path `e.g. end with /quartz` or have a trailing `/`.\n\n[Reference `deploy.yaml` here](https://github.com/jackyzha0/quartz/blob/hugo/.github/workflows/deploy.yaml)\n\n```yaml {title=\".github/workflows/deploy.yaml\"}\n- name: Deploy \n uses: peaceiris/actions-gh-pages@v3 \n with: \n\tgithub_token: ${{ secrets.GITHUB_TOKEN }} # this can stay as is, GitHub fills this in for us!\n\tpublish_dir: ./public \n\tpublish_branch: master\n\tcname: \u003cYOUR-DOMAIN\u003e\n```\n\nHave a custom domain? [Learn how to set it up with Quartz ](notes/custom%20Domain.md).\n\n### Ignoring Files\nOnly want to publish a subset of all of your notes? Don't worry, Quartz makes this a simple two-step process.\n\n❌ [Excluding pages from being published](notes/ignore%20notes.md)\n\n## Docker Support\nIf you don't want to use a hosting service, you can host using [Docker](notes/docker.md) instead!\nI would *not use this method* unless you know what you are doing.\n\n---\n\nNow that your Quartz is live, let's figure out how to make Quartz really *yours*!\n\n\u003e Step 6: 🎨 [Customizing Quartz](notes/config.md)\n\nHaving problems? Checkout our [FAQ and Troubleshooting guide](notes/troubleshooting.md).\n",
"lastmodified": "2022-12-31T02:53:43.344377399Z",
"tags": null
},
"/notes/ignore-notes": {
"title": "Ignoring Notes",
"content": "\n### Quartz Ignore\nEdit `ignoreFiles` in `config.toml` to include paths you'd like to exclude from being rendered.\n\n```toml\n...\nignoreFiles = [ \n \"/content/templates/*\", \n \"/content/private/*\", \n \"\u003cyour path here\u003e\"\n]\n```\n\n`ignoreFiles` supports the use of Regular Expressions (RegEx) so you can ignore patterns as well (e.g. ignoring all `.png`s by doing `\\\\.png$`).\nTo ignore a specific file, you can also add the tag `draft: true` to the frontmatter of a note.\n\n```markdown\n---\ntitle: Some Private Note\ndraft: true\n---\n...\n```\n\nMore details in [Hugo's documentation](https://gohugo.io/getting-started/configuration/#ignore-content-and-data-files-when-rendering).\n\n### Global Ignore\nHowever, just adding to the `ignoreFiles` will only prevent the page from being access through Quartz. If you want to prevent the file from being pushed to GitHub (for example if you have a public repository), you need to also add the path to the `.gitignore` file at the root of the repository.",
"lastmodified": "2022-12-31T02:53:43.344377399Z",
"tags": null
},
"/notes/obsidian": {
"title": "Obsidian Vault Integration",
"content": "\n## Setup\nObsidian is the preferred way to use Quartz. You can either create a new Obsidian Vault or link one that your already have.\n\n### New Vault\nIf you don't have an existing Vault, [download Obsidian](https://obsidian.md/) and create a new Vault in the `/content` folder that you created and cloned during the [setup](notes/setup.md) step.\n\n### Linking an existing Vault\nThe easiest way to use an existing Vault is to copy all of your files (directory and hierarchies intact) into the `/content` folder.\n\n## Settings\nGreat, now that you have your Obsidian linked to your Quartz, let's fix some settings so that they play well.\n\n1. Under Options \u003e Files and Links, set the New link format to always use Absolute Path in Vault.\n2. Go to Settings \u003e Files \u0026 Links \u003e Turn \"on\" automatically update internal links.\n\n![Obsidian Settings](/notes/images/obsidian-settings.png)*Obsidian Settings*\n\n## Templates\nInserting front matter everytime you want to create a new Note gets annoying really quickly. Luckily, Obsidian supports templates which makes inserting new content really easily.\n\n**If you decide to overwrite the `/content` folder completely, don't remove the `/content/templates` folder!**\n\nHead over to Options \u003e Core Plugins and enable the Templates plugin. Then go to Options \u003e Hotkeys and set a hotkey for 'Insert Template' (I recommend `[cmd]+T`). That way, when you create a new note, you can just press the hotkey for a new template and be ready to go!\n\n\u003e 👀 Step 4: [Preview Quartz Changes](notes/preview%20changes.md)",
"lastmodified": "2022-12-31T02:53:43.348377376Z",
"tags": null
},
"/notes/philosophy": {
"title": "Quartz Philosophy",
"content": "\n\u003e “[One] who works with the door open gets all kinds of interruptions, but [they] also occasionally gets clues as to what the world is and what might be important.” — Richard Hamming\n\n## Why Quartz?\nHosting a public digital garden isn't easy. There are an overwhelming number of tutorials, resources, and guides for tools like [Notion](https://www.notion.so/), [Roam](https://roamresearch.com/), and [Obsidian](https://obsidian.md/), yet none of them have super easy to use *free* tools to publish that garden to the world.\n\nI've personally found that\n1. It's nice to access notes from anywhere\n2. Having a public digital garden invites open conversations\n3. It makes keeping personal notes and knowledge *playful and fun*\n\nI was really inspired by [Bianca](https://garden.bianca.digital/) and [Joel](https://joelhooks.com/digital-garden)'s digital gardens and wanted to try making my own.\n\n**The goal of Quartz is to make hosting your own public digital garden free and simple.** You don't even need your own website. Quartz does all of that for you and gives your own little corner of the internet.\n",
"lastmodified": "2022-12-31T02:53:43.348377376Z",
"tags": null
},
"/notes/preview-changes": {
"title": "Preview Changes",
"content": "\nIf you'd like to preview what your Quartz site looks like before deploying it to the internet, the following\ninstructions guide you through installing the proper dependencies to run it locally.\n\n\n## Install `hugo-obsidian`\nThis step will generate the list of backlinks for Hugo to parse. Ensure you have [Go](https://golang.org/doc/install) (\u003e= 1.16) installed.\n\n```bash\n# Install and link `hugo-obsidian` locally\ngo install github.com/jackyzha0/hugo-obsidian@latest\n```\n\nIf you are running into an error saying that `command not found: hugo-obsidian`, make sure you set your `GOPATH` correctly! This will allow your terminal to correctly recognize hugo-obsidian as an executable.\n\nAfterwards, start the Hugo server as shown above and your local backlinks and interactive graph should be populated!\n\n## Installing Hugo\nHugo is the static site generator that powers Quartz. [Install Hugo with \"extended\" Sass/SCSS version](https://gohugo.io/getting-started/installing/) first. Then,\n\n```bash\n# Navigate to your local Quartz folder\ncd \u003clocation-of-your-local-quartz\u003e\n\n# Start local server\nmake serve\n\n# View your site in a browser at http://localhost:1313/\n```\n\n\u003e [!INFO] Docker Support\n\u003e\n\u003e If you have Docker installed already, open your terminal, navigate to your folder with Quartz and run `make docker`\n\nNow that you are happy with how your Quartz instance looks, let's get it hosted!\n\n\u003e 🌍 Step 5: [Hosting Quartz online!](notes/hosting.md)\n",
"lastmodified": "2022-12-31T02:53:43.348377376Z",
"tags": null
},
"/notes/search": {
"title": "Search",
"content": "\nQuartz supports two modes of searching through content.\n\n## Full-text\nFull-text search is the default in Quartz. It produces results that *exactly* match the search query. This is easier to setup but usually produces lower quality matches.\n\n```yaml {title=\"data/config.yaml\"}\n# the default option\nenableSemanticSearch: false\n```\n\n## Natural Language\nNatural language search is powered by [Operand](https://beta.operand.ai/). It understands language like a person does and finds results that best match user intent. In this sense, it is closer to how Google Search works.\n\nNatural language search tends to produce higher quality results than full-text search.\n\nHere's how to set it up.\n\n1. Login or Register for a new Operand account. Click the verification link sent to your email, and you'll be redirected to the dashboard. (Note) You do not need to enter a credit card to create an account, or get started with the Operand API. The first $10 of usage each month is free. To learn more, see pricing. If you go over your free quota, we'll (politely) reach out and ask you to configure billing.\n2. Create your first index. On the dashboard, under \"Indexes\", enter the name and description of your index, and click \"Create Index\". Note down the ID of the index (obtained by clicking on the index name in the list of indexes), as you'll need it in the next step. IDs are unique to each index, and look something like `uqv1duxxbdxu`.\n3. Click into the index you've created. Under \"Index Something\", select \"SITEMAP\" from the dropdown and click \"Add Source\".\n4. For the \"Sitemap.xml URL\", put your deployed site's base URL followed by `sitemap.xml`. For example, for `quartz.jzhao.xyz`, put `https://quartz.jzhao.xyz/sitemap.xml`. Leave the URL Regex empty. \n5. Get your API key. On the dashboard, under \"API Keys\", you can manage your API keys. If you don't already have an API key, click \"Create API Key\". You'll need this for the next step.\n6. Open `data/config.yaml`. Set `enableSemanticSearch` to `true`, `operandApiKey` to your copied key, and `operandIndexId` to the ID of the index we created from earlier..\n\n```yaml {title=\"data/config.yaml\"}\n# the default option\nsearch:\n enableSemanticSearch: true\n operandApiKey: \"jp9k5hudse2a828z98kxd6z3payi8u90rnjf\"\n operandIndexId: \"s0kf3bd6tldw\"\n```\n7. Push your changes to the site and wait for it to deploy.\n8. Check the Operand dashboard and wait for your site to index. Enjoy natural language search powered by Operand!\n",
"lastmodified": "2022-12-31T02:53:43.348377376Z",
"tags": null
},
"/notes/setup": {
"title": "Setup",
"content": "\n## Making your own Quartz\nSetting up Quartz requires a basic understanding of `git`. If you are unfamiliar, [this resource](https://resources.nwplus.io/2-beginner/how-to-git-github.html) is a great place to start!\n\n### Forking\n\u003e A fork is a copy of a repository. Forking a repository allows you to freely experiment with changes without affecting the original project.\n\nNavigate to the GitHub repository for the Quartz project:\n\n📁 [Quartz Repository](https://github.com/jackyzha0/quartz)\n\nThen, Fork the repository into your own GitHub account. If you don't have an account, you can make on for free [here](https://github.com/join). More details about forking a repo can be found on [GitHub's documentation](https://docs.github.com/en/get-started/quickstart/fork-a-repo).\n\n### Cloning\nAfter you've made a fork of the repository, you need to download the files locally onto your machine. Ensure you have `git`, then type the following command replacing `YOUR-USERNAME` with your GitHub username.\n\n```shell\ngit clone https://github.com/YOUR-USERNAME/quartz\n```\n\n## Editing\nGreat! Now you have everything you need to start editing and growing your digital garden. If you're ready to start writing content already, check out the recommended flow for editing notes in Quartz.\n\n\u003e ✏️ Step 2: [Editing Notes in Quartz](notes/editing.md)\n\nHaving problems? Checkout our [FAQ and Troubleshooting guide](notes/troubleshooting.md).\n",
"lastmodified": "2022-12-31T02:53:43.348377376Z",
"tags": null
},
"/notes/showcase": {
"title": "Showcase",
"content": "\nWant to see what Quartz can do? Here are some cool community gardens :)\n\n- [Quartz Documentation (this site!)](https://quartz.jzhao.xyz/)\n- [Jacky Zhao's Garden](https://jzhao.xyz/)\n- [Scaling Synthesis - A hypertext research notebook](https://scalingsynthesis.com/)\n- [AWAGMI Intern Notes](https://notes.awagmi.xyz/)\n- [Shihyu's PKM](https://shihyuho.github.io/pkm/)\n- [Chloe's Garden](https://garden.chloeabrasada.online/)\n- [SlRvb's Site](https://slrvb.github.io/Site/)\n- [Course notes for Information Technology Advanced Theory](https://a2itnotes.github.io/quartz/)\n- [Brandon Boswell's Garden](https://brandonkboswell.com)\n- [Siyang's Courtyard](https://siyangsun.github.io/courtyard/)\n- [Data Dictionary 🧠](https://glossary.airbyte.com/)\n- [sspaeti.com's Second Brain](https://brain.sspaeti.com/)\n- [oldwinterの数字花园](https://garden.oldwinter.top/)\n- [SethMB Work](https://sethmb.xyz/)\n- [Abhijeet's Math Wiki](https://abhmul.github.io/quartz/Math-Wiki/)\n\nIf you want to see your own on here, submit a [Pull Request adding yourself to this file](https://github.com/jackyzha0/quartz/blob/hugo/content/notes/showcase.md)!\n",
"lastmodified": "2022-12-31T02:53:43.348377376Z",
"tags": null
},
"/notes/troubleshooting": {
"title": "Troubleshooting and FAQ",
"content": "\nStill having trouble? Here are a list of common questions and problems people encounter when installing Quartz.\n\nWhile you're here, join our [Discord](https://discord.gg/cRFFHYye7t) :)\n\n### Does Quartz have Latex support?\nYes! See [CJK + Latex Support (测试)](notes/CJK%20+%20Latex%20Support%20(测试).md) for a brief demo.\n\n### Can I use \\\u003cObsidian Plugin\\\u003e in Quartz?\nUnless it produces direct Markdown output in the file, no. There currently is no way to bundle plugin code with Quartz.\n\nThe easiest way would be to add your own HTML partial that supports the functionality you are looking for.\n\n### My GitHub pages is just showing the README and not Quartz\nMake sure you set the source to deploy from `master` (and not `hugo`) using `/ (root)`! See more in the [hosting](/notes/hosting) guide\n\n### Some of my pages have 'January 1, 0001' as the last modified date\nThis is a problem caused by `git` treating files as case-insensitive by default and some of your posts probably have capitalized file names. You can turn this off in your Quartz by running this command.\n\n```shell\n# in the root of your Quartz (same folder as config.toml)\ngit config core.ignorecase true\n\n# or globally (not recommended)\ngit config --global core.ignorecase true\n```\n\n### Can I publish only a subset of my pages?\nYes! Quartz makes selective publishing really easy. Heres a guide on [excluding pages from being published](notes/ignore%20notes.md).\n\n### Can I host this myself and not on GitHub Pages?\nYes! All built files can be found under `/public` in the `master` branch. More details under [hosting](notes/hosting.md).\n\n### `command not found: hugo-obsidian`\nMake sure you set your `GOPATH` correctly! This will allow your terminal to correctly recognize `hugo-obsidian` as an executable.\n\n```shell\n# Add the following 2 lines to your ~/.bash_profile\nexport GOPATH=/Users/$USER/go\nexport PATH=$GOPATH/bin:$PATH\n\n# In your current terminal, to reload the session\nsource ~/.bash_profile\n```\n\n### How come my notes aren't being rendered?\nYou probably forgot to include front matter in your Markdown files. You can either setup [Obsidian](notes/obsidian.md) to do this for you or you need to manually define it. More details in [the 'how to edit' guide](notes/editing.md).\n\n### My custom domain isn't working!\nWalk through the steps in [the hosting guide](notes/hosting.md) again. Make sure you wait 30 min to 1 hour for changes to take effect.\n\n### How do I setup Google Analytics?\nYou can edit it in `config.toml` and either use a V3 (UA-) or V4 (G-) tag.\n\n### How do I change the content on the home page?\nTo edit the main home page, open `/content/_index.md`.\n\n### How do I change the colours?\nYou can change the theme by editing `assets/custom.scss`. More details on customization and themeing can be found in the [customization guide](notes/config.md).\n\n### How do I add images?\nYou can put images anywhere in the `/content` folder.\n\n```markdown\nExample image (source is in content/notes/images/example.png)\n![Example Image](/content/notes/images/example.png)\n```\n\n### My Interactive Graph and Backlinks aren't up to date\nBy default, the `linkIndex.json` (which Quartz needs to generate the Interactive Graph and Backlinks) are not regenerated locally. To set that up, see the guide on [local editing](notes/editing.md)\n\n### Can I use React/Vue/some other framework?\nNot out of the box. You could probably make it work by editing `/layouts/_default/single.html` but that's not what Quartz is designed to work with. 99% of things you are trying to do with those frameworks you can accomplish perfectly fine using just vanilla HTML/CSS/JS.\n\n## Still Stuck?\nQuartz isn't perfect! If you're still having troubles, file an issue in the GitHub repo with as much information as you can reasonably provide. Alternatively, you can message me on [Twitter](https://twitter.com/_jzhao) and I'll try to get back to you as soon as I can.\n\n🐛 [Submit an Issue](https://github.com/jackyzha0/quartz/issues)",
"lastmodified": "2022-12-31T02:53:43.348377376Z",
"tags": null
},
"/notes/updating": {
"title": "Updating",
"content": "\nHaven't updated Quartz in a while and want all the cool new optimizations? On Unix/Mac systems you can run the following command for a one-line update! This command will show you a log summary of all commits since you last updated, press `q` to acknowledge this. Then, it will show you each change in turn and press `y` to accept the patch or `n` to reject it. Usually you should press `y` for most of these unless it conflicts with existing changes you've made! \n\n```shell\nmake update\n```\n\nOr, if you don't want the interactive parts and just want to force update your local garden (this assumed that you are okay with some of your personalizations been overriden!)\n\n```shell\nmake update-force\n```\n\nOr, manually checkout the changes yourself.\n\n\u003e [!warning] Warning!\n\u003e\n\u003e If you customized the files in `data/`, or anything inside `layouts/`, your customization may be overwritten!\n\u003e Make sure you have a copy of these changes if you don't want to lose them.\n\n\n```shell\n# add Quartz as a remote host\ngit remote add upstream git@github.com:jackyzha0/quartz.git\n\n# index and fetch changes\ngit fetch upstream\ngit checkout -p upstream/hugo -- layouts .github Makefile assets/js assets/styles/base.scss assets/styles/darkmode.scss config.toml data \n```\n",
"lastmodified": "2022-12-31T02:53:43.348377376Z",
"tags": null
},
"/posts/": {
"title": "Blog",
"content": "",
"lastmodified": "2022-12-31T01:56:53.430566995Z",
"tags": null
},
"/posts/creating-a-new-theme": {
"title": "Creating a New Theme",
"content": "\n\n## Introduction\n\nThis tutorial will show you how to create a simple theme in Hugo. I assume that you are familiar with HTML, the bash command line, and that you are comfortable using Markdown to format content. I'll explain how Hugo uses templates and how you can organize your templates to create a theme. I won't cover using CSS to style your theme.\n\nWe'll start with creating a new site with a very basic template. Then we'll add in a few pages and posts. With small variations on that, you will be able to create many different types of web sites.\n\nIn this tutorial, commands that you enter will start with the \"$\" prompt. The output will follow. Lines that start with \"#\" are comments that I've added to explain a point. When I show updates to a file, the \":wq\" on the last line means to save the file.\n\nHere's an example:\n\n```\n## this is a comment\n$ echo this is a command\nthis is a command\n\n## edit the file\n$ vi foo.md\n+++\ndate = \"2014-09-28\"\ntitle = \"creating a new theme\"\n+++\n\nbah and humbug\n:wq\n\n## show it\n$ cat foo.md\n+++\ndate = \"2014-09-28\"\ntitle = \"creating a new theme\"\n+++\n\nbah and humbug\n$\n```\n\n\n## Some Definitions\n\nThere are a few concepts that you need to understand before creating a theme.\n\n### Skins\n\nSkins are the files responsible for the look and feel of your site. It’s the CSS that controls colors and fonts, it’s the Javascript that determines actions and reactions. It’s also the rules that Hugo uses to transform your content into the HTML that the site will serve to visitors.\n\nYou have two ways to create a skin. The simplest way is to create it in the ```layouts/``` directory. If you do, then you don’t have to worry about configuring Hugo to recognize it. The first place that Hugo will look for rules and files is in the ```layouts/``` directory so it will always find the skin.\n\nYour second choice is to create it in a sub-directory of the ```themes/``` directory. If you do, then you must always tell Hugo where to search for the skin. It’s extra work, though, so why bother with it?\n\nThe difference between creating a skin in ```layouts/``` and creating it in ```themes/``` is very subtle. A skin in ```layouts/``` can’t be customized without updating the templates and static files that it is built from. A skin created in ```themes/```, on the other hand, can be and that makes it easier for other people to use it.\n\nThe rest of this tutorial will call a skin created in the ```themes/``` directory a theme.\n\nNote that you can use this tutorial to create a skin in the ```layouts/``` directory if you wish to. The main difference will be that you won’t need to update the site’s configuration file to use a theme.\n\n### The Home Page\n\nThe home page, or landing page, is the first page that many visitors to a site see. It is the index.html file in the root directory of the web site. Since Hugo writes files to the public/ directory, our home page is public/index.html.\n\n### Site Configuration File\n\nWhen Hugo runs, it looks for a configuration file that contains settings that override default values for the entire site. The file can use TOML, YAML, or JSON. I prefer to use TOML for my configuration files. If you prefer to use JSON or YAML, you’ll need to translate my examples. You’ll also need to change the name of the file since Hugo uses the extension to determine how to process it.\n\nHugo translates Markdown files into HTML. By default, Hugo expects to find Markdown files in your ```content/``` directory and template files in your ```themes/``` directory. It will create HTML files in your ```public/``` directory. You can change this by specifying alternate locations in the configuration file.\n\n### Content\n\nContent is stored in text files that contain two sections. The first section is the “front matter,” which is the meta-information on the content. The second section contains Markdown that will be converted to HTML.\n\n#### Front Matter\n\nThe front matter is information about the content. Like the configuration file, it can be written in TOML, YAML, or JSON. Unlike the configuration file, Hugo doesn’t use the file’s extension to know the format. It looks for markers to signal the type. TOML is surrounded by “`+++`”, YAML by “`---`”, and JSON is enclosed in curly braces. I prefer to use TOML, so you’ll need to translate my examples if you prefer YAML or JSON.\n\nThe information in the front matter is passed into the template before the content is rendered into HTML.\n\n#### Markdown\n\nContent is written in Markdown which makes it easier to create the content. Hugo runs the content through a Markdown engine to create the HTML which will be written to the output file.\n\n### Template Files\n\nHugo uses template files to render content into HTML. Template files are a bridge between the content and presentation. Rules in the template define what content is published, where it's published to, and how it will rendered to the HTML file. The template guides the presentation by specifying the style to use.\n\nThere are three types of templates: single, list, and partial. Each type takes a bit of content as input and transforms it based on the commands in the template.\n\nHugo uses its knowledge of the content to find the template file used to render the content. If it can’t find a template that is an exact match for the content, it will shift up a level and search from there. It will continue to do so until it finds a matching template or runs out of templates to try. If it can’t find a template, it will use the default template for the site.\n\nPlease note that you can use the front matter to influence Hugo’s choice of templates.\n\n#### Single Template\n\nA single template is used to render a single piece of content. For example, an article or post would be a single piece of content and use a single template.\n\n#### List Template\n\nA list template renders a group of related content. That could be a summary of recent postings or all articles in a category. List templates can contain multiple groups.\n\nThe homepage template is a special type of list template. Hugo assumes that the home page of your site will act as the portal for the rest of the content in the site.\n\n#### Partial Template\n\nA partial template is a template that can be included in other templates. Partial templates must be called using the “partial” template command. They are very handy for rolling up common behavior. For example, your site may have a banner that all pages use. Instead of copying the text of the banner into every single and list template, you could create a partial with the banner in it. That way if you decide to change the banner, you only have to change the partial template.\n\n## Create a New Site\n\nLet's use Hugo to create a new web site. I'm a Mac user, so I'll create mine in my home directory, in the Sites folder. If you're using Linux, you might have to create the folder first.\n\nThe \"new site\" command will create a skeleton of a site. It will give you the basic directory structure and a useable configuration file.\n\n```\n$ hugo new site ~/Sites/zafta\n$ cd ~/Sites/zafta\n$ ls -l\ntotal 8\ndrwxr-xr-x 7 quoha staff 238 Sep 29 16:49 .\ndrwxr-xr-x 3 quoha staff 102 Sep 29 16:49 ..\ndrwxr-xr-x 2 quoha staff 68 Sep 29 16:49 archetypes\n-rw-r--r-- 1 quoha staff 82 Sep 29 16:49 config.toml\ndrwxr-xr-x 2 quoha staff 68 Sep 29 16:49 content\ndrwxr-xr-x 2 quoha staff 68 Sep 29 16:49 layouts\ndrwxr-xr-x 2 quoha staff 68 Sep 29 16:49 static\n$\n```\n\nTake a look in the content/ directory to confirm that it is empty.\n\nThe other directories (archetypes/, layouts/, and static/) are used when customizing a theme. That's a topic for a different tutorial, so please ignore them for now.\n\n### Generate the HTML For the New Site\n\nRunning the `hugo` command with no options will read all the available content and generate the HTML files. It will also copy all static files (that's everything that's not content). Since we have an empty site, it won't do much, but it will do it very quickly.\n\n```\n$ hugo --verbose\nINFO: 2014/09/29 Using config file: config.toml\nINFO: 2014/09/29 syncing from /Users/quoha/Sites/zafta/static/ to /Users/quoha/Sites/zafta/public/\nWARN: 2014/09/29 Unable to locate layout: [index.html _default/list.html _default/single.html]\nWARN: 2014/09/29 Unable to locate layout: [404.html]\n0 draft content \n0 future content \n0 pages created \n0 tags created\n0 categories created\nin 2 ms\n$ \n```\n\nThe \"`--verbose`\" flag gives extra information that will be helpful when we build the template. Every line of the output that starts with \"INFO:\" or \"WARN:\" is present because we used that flag. The lines that start with \"WARN:\" are warning messages. We'll go over them later.\n\nWe can verify that the command worked by looking at the directory again.\n\n```\n$ ls -l\ntotal 8\ndrwxr-xr-x 2 quoha staff 68 Sep 29 16:49 archetypes\n-rw-r--r-- 1 quoha staff 82 Sep 29 16:49 config.toml\ndrwxr-xr-x 2 quoha staff 68 Sep 29 16:49 content\ndrwxr-xr-x 2 quoha staff 68 Sep 29 16:49 layouts\ndrwxr-xr-x 4 quoha staff 136 Sep 29 17:02 public\ndrwxr-xr-x 2 quoha staff 68 Sep 29 16:49 static\n$\n```\n\nSee that new public/ directory? Hugo placed all generated content there. When you're ready to publish your web site, that's the place to start. For now, though, let's just confirm that we have what we'd expect from a site with no content.\n\n```\n$ ls -l public\ntotal 16\n-rw-r--r-- 1 quoha staff 416 Sep 29 17:02 index.xml\n-rw-r--r-- 1 quoha staff 262 Sep 29 17:02 sitemap.xml\n$ \n```\n\nHugo created two XML files, which is standard, but there are no HTML files.\n\n\n\n### Test the New Site\n\nVerify that you can run the built-in web server. It will dramatically shorten your development cycle if you do. Start it by running the \"server\" command. If it is successful, you will see output similar to the following:\n\n```\n$ hugo server --verbose\nINFO: 2014/09/29 Using config file: /Users/quoha/Sites/zafta/config.toml\nINFO: 2014/09/29 syncing from /Users/quoha/Sites/zafta/static/ to /Users/quoha/Sites/zafta/public/\nWARN: 2014/09/29 Unable to locate layout: [index.html _default/list.html _default/single.html]\nWARN: 2014/09/29 Unable to locate layout: [404.html]\n0 draft content \n0 future content \n0 pages created \n0 tags created\n0 categories created\nin 2 ms\nServing pages from /Users/quoha/Sites/zafta/public\nWeb Server is available at http://localhost:1313\nPress Ctrl+C to stop\n```\n\nConnect to the listed URL (it's on the line that starts with \"Web Server\"). If everything is working correctly, you should get a page that shows the following:\n\n```\nindex.xml\nsitemap.xml\n```\n\nThat's a listing of your public/ directory. Hugo didn't create a home page because our site has no content. When there's no index.html file in a directory, the server lists the files in the directory, which is what you should see in your browser.\n\nLet’s go back and look at those warnings again.\n\n```\nWARN: 2014/09/29 Unable to locate layout: [index.html _default/list.html _default/single.html]\nWARN: 2014/09/29 Unable to locate layout: [404.html]\n```\n\nThat second warning is easier to explain. We haven’t created a template to be used to generate “page not found errors.” The 404 message is a topic for a separate tutorial.\n\nNow for the first warning. It is for the home page. You can tell because the first layout that it looked for was “index.html.” That’s only used by the home page.\n\nI like that the verbose flag causes Hugo to list the files that it's searching for. For the home page, they are index.html, _default/list.html, and _default/single.html. There are some rules that we'll cover later that explain the names and paths. For now, just remember that Hugo couldn't find a template for the home page and it told you so.\n\nAt this point, you've got a working installation and site that we can build upon. All that’s left is to add some content and a theme to display it.\n\n## Create a New Theme\n\nHugo doesn't ship with a default theme. There are a few available (I counted a dozen when I first installed Hugo) and Hugo comes with a command to create new themes.\n\nWe're going to create a new theme called \"zafta.\" Since the goal of this tutorial is to show you how to fill out the files to pull in your content, the theme will not contain any CSS. In other words, ugly but functional.\n\nAll themes have opinions on content and layout. For example, Zafta uses \"post\" over \"blog\". Strong opinions make for simpler templates but differing opinions make it tougher to use themes. When you build a theme, consider using the terms that other themes do.\n\n\n### Create a Skeleton\n\nUse the hugo \"new\" command to create the skeleton of a theme. This creates the directory structure and places empty files for you to fill out.\n\n```\n$ hugo new theme zafta\n\n$ ls -l\ntotal 8\ndrwxr-xr-x 2 quoha staff 68 Sep 29 16:49 archetypes\n-rw-r--r-- 1 quoha staff 82 Sep 29 16:49 config.toml\ndrwxr-xr-x 2 quoha staff 68 Sep 29 16:49 content\ndrwxr-xr-x 2 quoha staff 68 Sep 29 16:49 layouts\ndrwxr-xr-x 4 quoha staff 136 Sep 29 17:02 public\ndrwxr-xr-x 2 quoha staff 68 Sep 29 16:49 static\ndrwxr-xr-x 3 quoha staff 102 Sep 29 17:31 themes\n\n$ find themes -type f | xargs ls -l\n-rw-r--r-- 1 quoha staff 1081 Sep 29 17:31 themes/zafta/LICENSE.md\n-rw-r--r-- 1 quoha staff 0 Sep 29 17:31 themes/zafta/archetypes/default.md\n-rw-r--r-- 1 quoha staff 0 Sep 29 17:31 themes/zafta/layouts/_default/list.html\n-rw-r--r-- 1 quoha staff 0 Sep 29 17:31 themes/zafta/layouts/_default/single.html\n-rw-r--r-- 1 quoha staff 0 Sep 29 17:31 themes/zafta/layouts/index.html\n-rw-r--r-- 1 quoha staff 0 Sep 29 17:31 themes/zafta/layouts/partials/footer.html\n-rw-r--r-- 1 quoha staff 0 Sep 29 17:31 themes/zafta/layouts/partials/header.html\n-rw-r--r-- 1 quoha staff 93 Sep 29 17:31 themes/zafta/theme.toml\n$ \n```\n\nThe skeleton includes templates (the files ending in .html), license file, a description of your theme (the theme.toml file), and an empty archetype.\n\nPlease take a minute to fill out the theme.toml and LICENSE.md files. They're optional, but if you're going to be distributing your theme, it tells the world who to praise (or blame). It's also nice to declare the license so that people will know how they can use the theme.\n\n```\n$ vi themes/zafta/theme.toml\nauthor = \"michael d henderson\"\ndescription = \"a minimal working template\"\nlicense = \"MIT\"\nname = \"zafta\"\nsource_repo = \"\"\ntags = [\"tags\", \"categories\"]\n:wq\n\n## also edit themes/zafta/LICENSE.md and change\n## the bit that says \"YOUR_NAME_HERE\"\n```\n\nNote that the the skeleton's template files are empty. Don't worry, we'll be changing that shortly.\n\n```\n$ find themes/zafta -name '*.html' | xargs ls -l\n-rw-r--r-- 1 quoha staff 0 Sep 29 17:31 themes/zafta/layouts/_default/list.html\n-rw-r--r-- 1 quoha staff 0 Sep 29 17:31 themes/zafta/layouts/_default/single.html\n-rw-r--r-- 1 quoha staff 0 Sep 29 17:31 themes/zafta/layouts/index.html\n-rw-r--r-- 1 quoha staff 0 Sep 29 17:31 themes/zafta/layouts/partials/footer.html\n-rw-r--r-- 1 quoha staff 0 Sep 29 17:31 themes/zafta/layouts/partials/header.html\n$\n```\n\n\n\n### Update the Configuration File to Use the Theme\n\nNow that we've got a theme to work with, it's a good idea to add the theme name to the configuration file. This is optional, because you can always add \"-t zafta\" on all your commands. I like to put it the configuration file because I like shorter command lines. If you don't put it in the configuration file or specify it on the command line, you won't use the template that you're expecting to.\n\nEdit the file to add the theme, add a title for the site, and specify that all of our content will use the TOML format.\n\n```\n$ vi config.toml\ntheme = \"zafta\"\nbaseurl = \"\"\nlanguageCode = \"en-us\"\ntitle = \"zafta - totally refreshing\"\nMetaDataFormat = \"toml\"\n:wq\n\n$\n```\n\n### Generate the Site\n\nNow that we have an empty theme, let's generate the site again.\n\n```\n$ hugo --verbose\nINFO: 2014/09/29 Using config file: /Users/quoha/Sites/zafta/config.toml\nINFO: 2014/09/29 syncing from /Users/quoha/Sites/zafta/themes/zafta/static/ to /Users/quoha/Sites/zafta/public/\nINFO: 2014/09/29 syncing from /Users/quoha/Sites/zafta/static/ to /Users/quoha/Sites/zafta/public/\nWARN: 2014/09/29 Unable to locate layout: [404.html theme/404.html]\n0 draft content \n0 future content \n0 pages created \n0 tags created\n0 categories created\nin 2 ms\n$\n```\n\nDid you notice that the output is different? The warning message for the home page has disappeared and we have an additional information line saying that Hugo is syncing from the theme's directory.\n\nLet's check the public/ directory to see what Hugo's created.\n\n```\n$ ls -l public\ntotal 16\ndrwxr-xr-x 2 quoha staff 68 Sep 29 17:56 css\n-rw-r--r-- 1 quoha staff 0 Sep 29 17:56 index.html\n-rw-r--r-- 1 quoha staff 407 Sep 29 17:56 index.xml\ndrwxr-xr-x 2 quoha staff 68 Sep 29 17:56 js\n-rw-r--r-- 1 quoha staff 243 Sep 29 17:56 sitemap.xml\n$\n```\n\nNotice four things:\n\n1. Hugo created a home page. This is the file public/index.html.\n2. Hugo created a css/ directory.\n3. Hugo created a js/ directory.\n4. Hugo claimed that it created 0 pages. It created a file and copied over static files, but didn't create any pages. That's because it considers a \"page\" to be a file created directly from a content file. It doesn't count things like the index.html files that it creates automatically.\n\n#### The Home Page\n\nHugo supports many different types of templates. The home page is special because it gets its own type of template and its own template file. The file, layouts/index.html, is used to generate the HTML for the home page. The Hugo documentation says that this is the only required template, but that depends. Hugo's warning message shows that it looks for three different templates:\n\n```\nWARN: 2014/09/29 Unable to locate layout: [index.html _default/list.html _default/single.html]\n```\n\nIf it can't find any of these, it completely skips creating the home page. We noticed that when we built the site without having a theme installed.\n\nWhen Hugo created our theme, it created an empty home page template. Now, when we build the site, Hugo finds the template and uses it to generate the HTML for the home page. Since the template file is empty, the HTML file is empty, too. If the template had any rules in it, then Hugo would have used them to generate the home page.\n\n```\n$ find . -name index.html | xargs ls -l\n-rw-r--r-- 1 quoha staff 0 Sep 29 20:21 ./public/index.html\n-rw-r--r-- 1 quoha staff 0 Sep 29 17:31 ./themes/zafta/layouts/index.html\n$ \n```\n\n#### The Magic of Static\n\nHugo does two things when generating the site. It uses templates to transform content into HTML and it copies static files into the site. Unlike content, static files are not transformed. They are copied exactly as they are.\n\nHugo assumes that your site will use both CSS and JavaScript, so it creates directories in your theme to hold them. Remember opinions? Well, Hugo's opinion is that you'll store your CSS in a directory named css/ and your JavaScript in a directory named js/. If you don't like that, you can change the directory names in your theme directory or even delete them completely. Hugo's nice enough to offer its opinion, then behave nicely if you disagree.\n\n```\n$ find themes/zafta -type d | xargs ls -ld\ndrwxr-xr-x 7 quoha staff 238 Sep 29 17:38 themes/zafta\ndrwxr-xr-x 3 quoha staff 102 Sep 29 17:31 themes/zafta/archetypes\ndrwxr-xr-x 5 quoha staff 170 Sep 29 17:31 themes/zafta/layouts\ndrwxr-xr-x 4 quoha staff 136 Sep 29 17:31 themes/zafta/layouts/_default\ndrwxr-xr-x 4 quoha staff 136 Sep 29 17:31 themes/zafta/layouts/partials\ndrwxr-xr-x 4 quoha staff 136 Sep 29 17:31 themes/zafta/static\ndrwxr-xr-x 2 quoha staff 68 Sep 29 17:31 themes/zafta/static/css\ndrwxr-xr-x 2 quoha staff 68 Sep 29 17:31 themes/zafta/static/js\n$ \n```\n\n## The Theme Development Cycle\n\nWhen you're working on a theme, you will make changes in the theme's directory, rebuild the site, and check your changes in the browser. Hugo makes this very easy:\n\n1. Purge the public/ directory.\n2. Run the built in web server in watch mode.\n3. Open your site in a browser.\n4. Update the theme.\n5. Glance at your browser window to see changes.\n6. Return to step 4.\n\nI’ll throw in one more opinion: never work on a theme on a live site. Always work on a copy of your site. Make changes to your theme, test them, then copy them up to your site. For added safety, use a tool like Git to keep a revision history of your content and your theme. Believe me when I say that it is too easy to lose both your mind and your changes.\n\nCheck the main Hugo site for information on using Git with Hugo.\n\n### Purge the public/ Directory\n\nWhen generating the site, Hugo will create new files and update existing ones in the ```public/``` directory. It will not delete files that are no longer used. For example, files that were created in the wrong directory or with the wrong title will remain. If you leave them, you might get confused by them later. I recommend cleaning out your site prior to generating it.\n\nNote: If you're building on an SSD, you should ignore this. Churning on a SSD can be costly.\n\n### Hugo's Watch Option\n\nHugo's \"`--watch`\" option will monitor the content/ and your theme directories for changes and rebuild the site automatically.\n\n### Live Reload\n\nHugo's built in web server supports live reload. As pages are saved on the server, the browser is told to refresh the page. Usually, this happens faster than you can say, \"Wow, that's totally amazing.\"\n\n### Development Commands\n\nUse the following commands as the basis for your workflow.\n\n```\n## purge old files. hugo will recreate the public directory.\n##\n$ rm -rf public\n##\n## run hugo in watch mode\n##\n$ hugo server --watch --verbose\n```\n\nHere's sample output showing Hugo detecting a change to the template for the home page. Once generated, the web browser automatically reloaded the page. I've said this before, it's amazing.\n\n\n```\n$ rm -rf public\n$ hugo server --watch --verbose\nINFO: 2014/09/29 Using config file: /Users/quoha/Sites/zafta/config.toml\nINFO: 2014/09/29 syncing from /Users/quoha/Sites/zafta/themes/zafta/static/ to /Users/quoha/Sites/zafta/public/\nINFO: 2014/09/29 syncing from /Users/quoha/Sites/zafta/static/ to /Users/quoha/Sites/zafta/public/\nWARN: 2014/09/29 Unable to locate layout: [404.html theme/404.html]\n0 draft content \n0 future content \n0 pages created \n0 tags created\n0 categories created\nin 2 ms\nWatching for changes in /Users/quoha/Sites/zafta/content\nServing pages from /Users/quoha/Sites/zafta/public\nWeb Server is available at http://localhost:1313\nPress Ctrl+C to stop\nINFO: 2014/09/29 File System Event: [\"/Users/quoha/Sites/zafta/themes/zafta/layouts/index.html\": MODIFY|ATTRIB]\nChange detected, rebuilding site\n\nWARN: 2014/09/29 Unable to locate layout: [404.html theme/404.html]\n0 draft content \n0 future content \n0 pages created \n0 tags created\n0 categories created\nin 1 ms\n```\n\n## Update the Home Page Template\n\nThe home page is one of a few special pages that Hugo creates automatically. As mentioned earlier, it looks for one of three files in the theme's layout/ directory:\n\n1. index.html\n2. _default/list.html\n3. _default/single.html\n\nWe could update one of the default templates, but a good design decision is to update the most specific template available. That's not a hard and fast rule (in fact, we'll break it a few times in this tutorial), but it is a good generalization.\n\n### Make a Static Home Page\n\nRight now, that page is empty because we don't have any content and we don't have any logic in the template. Let's change that by adding some text to the template.\n\n```\n$ vi themes/zafta/layouts/index.html\n\u003c!DOCTYPE html\u003e \n\u003chtml\u003e \n\u003cbody\u003e \n \u003cp\u003ehugo says hello!\u003c/p\u003e \n\u003c/body\u003e \n\u003c/html\u003e \n:wq\n\n$\n```\n\nBuild the web site and then verify the results.\n\n```\n$ hugo --verbose\nINFO: 2014/09/29 Using config file: /Users/quoha/Sites/zafta/config.toml\nINFO: 2014/09/29 syncing from /Users/quoha/Sites/zafta/themes/zafta/static/ to /Users/quoha/Sites/zafta/public/\nINFO: 2014/09/29 syncing from /Users/quoha/Sites/zafta/static/ to /Users/quoha/Sites/zafta/public/\nWARN: 2014/09/29 Unable to locate layout: [404.html theme/404.html]\n0 draft content \n0 future content \n0 pages created \n0 tags created\n0 categories created\nin 2 ms\n\n$ find public -type f -name '*.html' | xargs ls -l\n-rw-r--r-- 1 quoha staff 78 Sep 29 21:26 public/index.html\n\n$ cat public/index.html \n\u003c!DOCTYPE html\u003e \n\u003chtml\u003e \n\u003cbody\u003e \n \u003cp\u003ehugo says hello!\u003c/p\u003e \n\u003c/html\u003e\n```\n\n#### Live Reload\n\nNote: If you're running the server with the `--watch` option, you'll see different content in the file:\n\n```\n$ cat public/index.html \n\u003c!DOCTYPE html\u003e \n\u003chtml\u003e \n\u003cbody\u003e \n \u003cp\u003ehugo says hello!\u003c/p\u003e \n\u003cscript\u003edocument.write('\u003cscript src=\"http://' \n + (location.host || 'localhost').split(':')[0] \n + ':1313/livereload.js?mindelay=10\"\u003e\u003c/' \n + 'script\u003e')\u003c/script\u003e\u003c/body\u003e \n\u003c/html\u003e\n```\n\nWhen you use `--watch`, the Live Reload script is added by Hugo. Look for live reload in the documentation to see what it does and how to disable it.\n\n### Build a \"Dynamic\" Home Page\n\n\"Dynamic home page?\" Hugo's a static web site generator, so this seems an odd thing to say. I mean let's have the home page automatically reflect the content in the site every time Hugo builds it. We'll use iteration in the template to do that.\n\n#### Create New Posts\n\nNow that we have the home page generating static content, let's add some content to the site. We'll display these posts as a list on the home page and on their own page, too.\n\nHugo has a command to generate a skeleton post, just like it does for sites and themes.\n\n```\n$ hugo --verbose new post/first.md\nINFO: 2014/09/29 Using config file: /Users/quoha/Sites/zafta/config.toml\nINFO: 2014/09/29 attempting to create post/first.md of post\nINFO: 2014/09/29 curpath: /Users/quoha/Sites/zafta/themes/zafta/archetypes/default.md\nERROR: 2014/09/29 Unable to Cast \u003cnil\u003e to map[string]interface{}\n\n$ \n```\n\nThat wasn't very nice, was it?\n\nThe \"new\" command uses an archetype to create the post file. Hugo created an empty default archetype file, but that causes an error when there's a theme. For me, the workaround was to create an archetypes file specifically for the post type.\n\n```\n$ vi themes/zafta/archetypes/post.md\n+++\nDescription = \"\"\nTags = []\nCategories = []\n+++\n:wq\n\n$ find themes/zafta/archetypes -type f | xargs ls -l\n-rw-r--r-- 1 quoha staff 0 Sep 29 21:53 themes/zafta/archetypes/default.md\n-rw-r--r-- 1 quoha staff 51 Sep 29 21:54 themes/zafta/archetypes/post.md\n\n$ hugo --verbose new post/first.md\nINFO: 2014/09/29 Using config file: /Users/quoha/Sites/zafta/config.toml\nINFO: 2014/09/29 attempting to create post/first.md of post\nINFO: 2014/09/29 curpath: /Users/quoha/Sites/zafta/themes/zafta/archetypes/post.md\nINFO: 2014/09/29 creating /Users/quoha/Sites/zafta/content/post/first.md\n/Users/quoha/Sites/zafta/content/post/first.md created\n\n$ hugo --verbose new post/second.md\nINFO: 2014/09/29 Using config file: /Users/quoha/Sites/zafta/config.toml\nINFO: 2014/09/29 attempting to create post/second.md of post\nINFO: 2014/09/29 curpath: /Users/quoha/Sites/zafta/themes/zafta/archetypes/post.md\nINFO: 2014/09/29 creating /Users/quoha/Sites/zafta/content/post/second.md\n/Users/quoha/Sites/zafta/content/post/second.md created\n\n$ ls -l content/post\ntotal 16\n-rw-r--r-- 1 quoha staff 104 Sep 29 21:54 first.md\n-rw-r--r-- 1 quoha staff 105 Sep 29 21:57 second.md\n\n$ cat content/post/first.md \n+++\nCategories = []\nDescription = \"\"\nTags = []\ndate = \"2014-09-29T21:54:53-05:00\"\ntitle = \"first\"\n\n+++\nmy first post\n\n$ cat content/post/second.md \n+++\nCategories = []\nDescription = \"\"\nTags = []\ndate = \"2014-09-29T21:57:09-05:00\"\ntitle = \"second\"\n\n+++\nmy second post\n\n$ \n```\n\nBuild the web site and then verify the results.\n\n```\n$ rm -rf public\n$ hugo --verbose\nINFO: 2014/09/29 Using config file: /Users/quoha/Sites/zafta/config.toml\nINFO: 2014/09/29 syncing from /Users/quoha/Sites/zafta/themes/zafta/static/ to /Users/quoha/Sites/zafta/public/\nINFO: 2014/09/29 syncing from /Users/quoha/Sites/zafta/static/ to /Users/quoha/Sites/zafta/public/\nINFO: 2014/09/29 found taxonomies: map[string]string{\"category\":\"categories\", \"tag\":\"tags\"}\nWARN: 2014/09/29 Unable to locate layout: [404.html theme/404.html]\n0 draft content \n0 future content \n2 pages created \n0 tags created\n0 categories created\nin 4 ms\n$\n```\n\nThe output says that it created 2 pages. Those are our new posts:\n\n```\n$ find public -type f -name '*.html' | xargs ls -l\n-rw-r--r-- 1 quoha staff 78 Sep 29 22:13 public/index.html\n-rw-r--r-- 1 quoha staff 0 Sep 29 22:13 public/post/first/index.html\n-rw-r--r-- 1 quoha staff 0 Sep 29 22:13 public/post/index.html\n-rw-r--r-- 1 quoha staff 0 Sep 29 22:13 public/post/second/index.html\n$\n```\n\nThe new files are empty because because the templates used to generate the content are empty. The homepage doesn't show the new content, either. We have to update the templates to add the posts.\n\n### List and Single Templates\n\nIn Hugo, we have three major kinds of templates. There's the home page template that we updated previously. It is used only by the home page. We also have \"single\" templates which are used to generate output for a single content file. We also have \"list\" templates that are used to group multiple pieces of content before generating output.\n\nGenerally speaking, list templates are named \"list.html\" and single templates are named \"single.html.\"\n\nThere are three other types of templates: partials, content views, and terms. We will not go into much detail on these.\n\n### Add Content to the Homepage\n\nThe home page will contain a list of posts. Let's update its template to add the posts that we just created. The logic in the template will run every time we build the site.\n\n```\n$ vi themes/zafta/layouts/index.html \n\u003c!DOCTYPE html\u003e\n\u003chtml\u003e\n\u003cbody\u003e\n {{ range first 10 .Data.Pages }}\n \u003ch1\u003e{{ .Title }}\u003c/h1\u003e\n {{ end }}\n\u003c/body\u003e\n\u003c/html\u003e\n:wq\n\n$\n```\n\nHugo uses the Go template engine. That engine scans the template files for commands which are enclosed between \"{{\" and \"}}\". In our template, the commands are:\n\n1. range\n2. .Title\n3. end\n\nThe \"range\" command is an iterator. We're going to use it to go through the first ten pages. Every HTML file that Hugo creates is treated as a page, so looping through the list of pages will look at every file that will be created.\n\nThe \".Title\" command prints the value of the \"title\" variable. Hugo pulls it from the front matter in the Markdown file.\n\nThe \"end\" command signals the end of the range iterator. The engine loops back to the top of the iteration when it finds \"end.\" Everything between the \"range\" and \"end\" is evaluated every time the engine goes through the iteration. In this file, that would cause the title from the first ten pages to be output as heading level one.\n\nIt's helpful to remember that some variables, like .Data, are created before any output files. Hugo loads every content file into the variable and then gives the template a chance to process before creating the HTML files.\n\nBuild the web site and then verify the results.\n\n```\n$ rm -rf public\n$ hugo --verbose\nINFO: 2014/09/29 Using config file: /Users/quoha/Sites/zafta/config.toml\nINFO: 2014/09/29 syncing from /Users/quoha/Sites/zafta/themes/zafta/static/ to /Users/quoha/Sites/zafta/public/\nINFO: 2014/09/29 syncing from /Users/quoha/Sites/zafta/static/ to /Users/quoha/Sites/zafta/public/\nINFO: 2014/09/29 found taxonomies: map[string]string{\"tag\":\"tags\", \"category\":\"categories\"}\nWARN: 2014/09/29 Unable to locate layout: [404.html theme/404.html]\n0 draft content \n0 future content \n2 pages created \n0 tags created\n0 categories created\nin 4 ms\n$ find public -type f -name '*.html' | xargs ls -l \n-rw-r--r-- 1 quoha staff 94 Sep 29 22:23 public/index.html\n-rw-r--r-- 1 quoha staff 0 Sep 29 22:23 public/post/first/index.html\n-rw-r--r-- 1 quoha staff 0 Sep 29 22:23 public/post/index.html\n-rw-r--r-- 1 quoha staff 0 Sep 29 22:23 public/post/second/index.html\n$ cat public/index.html \n\u003c!DOCTYPE html\u003e\n\u003chtml\u003e\n\u003cbody\u003e\n \n \u003ch1\u003esecond\u003c/h1\u003e\n \n \u003ch1\u003efirst\u003c/h1\u003e\n \n\u003c/body\u003e\n\u003c/html\u003e\n$\n```\n\nCongratulations, the home page shows the title of the two posts. The posts themselves are still empty, but let's take a moment to appreciate what we've done. Your template now generates output dynamically. Believe it or not, by inserting the range command inside of those curly braces, you've learned everything you need to know to build a theme. All that's really left is understanding which template will be used to generate each content file and becoming familiar with the commands for the template engine.\n\nAnd, if that were entirely true, this tutorial would be much shorter. There are a few things to know that will make creating a new template much easier. Don't worry, though, that's all to come.\n\n### Add Content to the Posts\n\nWe're working with posts, which are in the content/post/ directory. That means that their section is \"post\" (and if we don't do something weird, their type is also \"post\").\n\nHugo uses the section and type to find the template file for every piece of content. Hugo will first look for a template file that matches the section or type name. If it can't find one, then it will look in the _default/ directory. There are some twists that we'll cover when we get to categories and tags, but for now we can assume that Hugo will try post/single.html, then _default/single.html.\n\nNow that we know the search rule, let's see what we actually have available:\n\n```\n$ find themes/zafta -name single.html | xargs ls -l\n-rw-r--r-- 1 quoha staff 132 Sep 29 17:31 themes/zafta/layouts/_default/single.html\n```\n\nWe could create a new template, post/single.html, or change the default. Since we don't know of any other content types, let's start with updating the default.\n\nRemember, any content that we haven't created a template for will end up using this template. That can be good or bad. Bad because I know that we're going to be adding different types of content and we're going to end up undoing some of the changes we've made. It's good because we'll be able to see immediate results. It's also good to start here because we can start to build the basic layout for the site. As we add more content types, we'll refactor this file and move logic around. Hugo makes that fairly painless, so we'll accept the cost and proceed.\n\nPlease see the Hugo documentation on template rendering for all the details on determining which template to use. And, as the docs mention, if you're building a single page application (SPA) web site, you can delete all of the other templates and work with just the default single page. That's a refreshing amount of joy right there.\n\n#### Update the Template File\n\n```\n$ vi themes/zafta/layouts/_default/single.html \n\u003c!DOCTYPE html\u003e\n\u003chtml\u003e\n\u003chead\u003e\n \u003ctitle\u003e{{ .Title }}\u003c/title\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n \u003ch1\u003e{{ .Title }}\u003c/h1\u003e\n {{ .Content }}\n\u003c/body\u003e\n\u003c/html\u003e\n:wq\n\n$\n```\n\nBuild the web site and verify the results.\n\n```\n$ rm -rf public\n$ hugo --verbose\nINFO: 2014/09/29 Using config file: /Users/quoha/Sites/zafta/config.toml\nINFO: 2014/09/29 syncing from /Users/quoha/Sites/zafta/themes/zafta/static/ to /Users/quoha/Sites/zafta/public/\nINFO: 2014/09/29 syncing from /Users/quoha/Sites/zafta/static/ to /Users/quoha/Sites/zafta/public/\nINFO: 2014/09/29 found taxonomies: map[string]string{\"tag\":\"tags\", \"category\":\"categories\"}\nWARN: 2014/09/29 Unable to locate layout: [404.html theme/404.html]\n0 draft content \n0 future content \n2 pages created \n0 tags created\n0 categories created\nin 4 ms\n\n$ find public -type f -name '*.html' | xargs ls -l\n-rw-r--r-- 1 quoha staff 94 Sep 29 22:40 public/index.html\n-rw-r--r-- 1 quoha staff 125 Sep 29 22:40 public/post/first/index.html\n-rw-r--r-- 1 quoha staff 0 Sep 29 22:40 public/post/index.html\n-rw-r--r-- 1 quoha staff 128 Sep 29 22:40 public/post/second/index.html\n\n$ cat public/post/first/index.html \n\u003c!DOCTYPE html\u003e\n\u003chtml\u003e\n\u003chead\u003e\n \u003ctitle\u003efirst\u003c/title\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n \u003ch1\u003efirst\u003c/h1\u003e\n \u003cp\u003emy first post\u003c/p\u003e\n\n\u003c/body\u003e\n\u003c/html\u003e\n\n$ cat public/post/second/index.html \n\u003c!DOCTYPE html\u003e\n\u003chtml\u003e\n\u003chead\u003e\n \u003ctitle\u003esecond\u003c/title\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n \u003ch1\u003esecond\u003c/h1\u003e\n \u003cp\u003emy second post\u003c/p\u003e\n\n\u003c/body\u003e\n\u003c/html\u003e\n$\n```\n\nNotice that the posts now have content. You can go to localhost:1313/post/first to verify.\n\n### Linking to Content\n\nThe posts are on the home page. Let's add a link from there to the post. Since this is the home page, we'll update its template.\n\n```\n$ vi themes/zafta/layouts/index.html\n\u003c!DOCTYPE html\u003e\n\u003chtml\u003e\n\u003cbody\u003e\n {{ range first 10 .Data.Pages }}\n \u003ch1\u003e\u003ca href=\"{{ .Permalink }}\"\u003e{{ .Title }}\u003c/a\u003e\u003c/h1\u003e\n {{ end }}\n\u003c/body\u003e\n\u003c/html\u003e\n```\n\nBuild the web site and verify the results.\n\n```\n$ rm -rf public\n$ hugo --verbose\nINFO: 2014/09/29 Using config file: /Users/quoha/Sites/zafta/config.toml\nINFO: 2014/09/29 syncing from /Users/quoha/Sites/zafta/themes/zafta/static/ to /Users/quoha/Sites/zafta/public/\nINFO: 2014/09/29 syncing from /Users/quoha/Sites/zafta/static/ to /Users/quoha/Sites/zafta/public/\nINFO: 2014/09/29 found taxonomies: map[string]string{\"tag\":\"tags\", \"category\":\"categories\"}\nWARN: 2014/09/29 Unable to locate layout: [404.html theme/404.html]\n0 draft content \n0 future content \n2 pages created \n0 tags created\n0 categories created\nin 4 ms\n\n$ find public -type f -name '*.html' | xargs ls -l\n-rw-r--r-- 1 quoha staff 149 Sep 29 22:44 public/index.html\n-rw-r--r-- 1 quoha staff 125 Sep 29 22:44 public/post/first/index.html\n-rw-r--r-- 1 quoha staff 0 Sep 29 22:44 public/post/index.html\n-rw-r--r-- 1 quoha staff 128 Sep 29 22:44 public/post/second/index.html\n\n$ cat public/index.html \n\u003c!DOCTYPE html\u003e\n\u003chtml\u003e\n\u003cbody\u003e\n \n \u003ch1\u003e\u003ca href=\"/post/second/\"\u003esecond\u003c/a\u003e\u003c/h1\u003e\n \n \u003ch1\u003e\u003ca href=\"/post/first/\"\u003efirst\u003c/a\u003e\u003c/h1\u003e\n \n\u003c/body\u003e\n\u003c/html\u003e\n\n$\n```\n\n### Create a Post Listing\n\nWe have the posts displaying on the home page and on their own page. We also have a file public/post/index.html that is empty. Let's make it show a list of all posts (not just the first ten).\n\nWe need to decide which template to update. This will be a listing, so it should be a list template. Let's take a quick look and see which list templates are available.\n\n```\n$ find themes/zafta -name list.html | xargs ls -l\n-rw-r--r-- 1 quoha staff 0 Sep 29 17:31 themes/zafta/layouts/_default/list.html\n```\n\nAs with the single post, we have to decide to update _default/list.html or create post/list.html. We still don't have multiple content types, so let's stay consistent and update the default list template.\n\n## Creating Top Level Pages\n\nLet's add an \"about\" page and display it at the top level (as opposed to a sub-level like we did with posts).\n\nThe default in Hugo is to use the directory structure of the content/ directory to guide the location of the generated html in the public/ directory. Let's verify that by creating an \"about\" page at the top level:\n\n```\n$ vi content/about.md \n+++\ntitle = \"about\"\ndescription = \"about this site\"\ndate = \"2014-09-27\"\nslug = \"about time\"\n+++\n\n## about us\n\ni'm speechless\n:wq\n```\n\nGenerate the web site and verify the results.\n\n```\n$ find public -name '*.html' | xargs ls -l\n-rw-rw-r-- 1 mdhender staff 334 Sep 27 15:08 public/about-time/index.html\n-rw-rw-r-- 1 mdhender staff 527 Sep 27 15:08 public/index.html\n-rw-rw-r-- 1 mdhender staff 358 Sep 27 15:08 public/post/first-post/index.html\n-rw-rw-r-- 1 mdhender staff 0 Sep 27 15:08 public/post/index.html\n-rw-rw-r-- 1 mdhender staff 342 Sep 27 15:08 public/post/second-post/index.html\n```\n\nNotice that the page wasn't created at the top level. It was created in a sub-directory named 'about-time/'. That name came from our slug. Hugo will use the slug to name the generated content. It's a reasonable default, by the way, but we can learn a few things by fighting it for this file.\n\nOne other thing. Take a look at the home page.\n\n```\n$ cat public/index.html\n\u003c!DOCTYPE html\u003e\n\u003chtml\u003e\n\u003cbody\u003e\n \u003ch1\u003e\u003ca href=\"http://localhost:1313/post/theme/\"\u003ecreating a new theme\u003c/a\u003e\u003c/h1\u003e\n \u003ch1\u003e\u003ca href=\"http://localhost:1313/about-time/\"\u003eabout\u003c/a\u003e\u003c/h1\u003e\n \u003ch1\u003e\u003ca href=\"http://localhost:1313/post/second-post/\"\u003esecond\u003c/a\u003e\u003c/h1\u003e\n \u003ch1\u003e\u003ca href=\"http://localhost:1313/post/first-post/\"\u003efirst\u003c/a\u003e\u003c/h1\u003e\n\u003cscript\u003edocument.write('\u003cscript src=\"http://'\n + (location.host || 'localhost').split(':')[0]\n\t\t+ ':1313/livereload.js?mindelay=10\"\u003e\u003c/'\n + 'script\u003e')\u003c/script\u003e\u003c/body\u003e\n\u003c/html\u003e\n```\n\nNotice that the \"about\" link is listed with the posts? That's not desirable, so let's change that first.\n\n```\n$ vi themes/zafta/layouts/index.html\n\u003c!DOCTYPE html\u003e\n\u003chtml\u003e\n\u003cbody\u003e\n \u003ch1\u003eposts\u003c/h1\u003e\n {{ range first 10 .Data.Pages }}\n {{ if eq .Type \"post\"}}\n \u003ch2\u003e\u003ca href=\"{{ .Permalink }}\"\u003e{{ .Title }}\u003c/a\u003e\u003c/h2\u003e\n {{ end }}\n {{ end }}\n\n \u003ch1\u003epages\u003c/h1\u003e\n {{ range .Data.Pages }}\n {{ if eq .Type \"page\" }}\n \u003ch2\u003e\u003ca href=\"{{ .Permalink }}\"\u003e{{ .Title }}\u003c/a\u003e\u003c/h2\u003e\n {{ end }}\n {{ end }}\n\u003c/body\u003e\n\u003c/html\u003e\n:wq\n```\n\nGenerate the web site and verify the results. The home page has two sections, posts and pages, and each section has the right set of headings and links in it.\n\nBut, that about page still renders to about-time/index.html.\n\n```\n$ find public -name '*.html' | xargs ls -l\n-rw-rw-r-- 1 mdhender staff 334 Sep 27 15:33 public/about-time/index.html\n-rw-rw-r-- 1 mdhender staff 645 Sep 27 15:33 public/index.html\n-rw-rw-r-- 1 mdhender staff 358 Sep 27 15:33 public/post/first-post/index.html\n-rw-rw-r-- 1 mdhender staff 0 Sep 27 15:33 public/post/index.html\n-rw-rw-r-- 1 mdhender staff 342 Sep 27 15:33 public/post/second-post/index.html\n```\n\nKnowing that hugo is using the slug to generate the file name, the simplest solution is to change the slug. Let's do it the hard way and change the permalink in the configuration file.\n\n```\n$ vi config.toml\n[permalinks]\n\tpage = \"/:title/\"\n\tabout = \"/:filename/\"\n```\n\nGenerate the web site and verify that this didn't work. Hugo lets \"slug\" or \"URL\" override the permalinks setting in the configuration file. Go ahead and comment out the slug in content/about.md, then generate the web site to get it to be created in the right place.\n\n## Sharing Templates\n\nIf you've been following along, you probably noticed that posts have titles in the browser and the home page doesn't. That's because we didn't put the title in the home page's template (layouts/index.html). That's an easy thing to do, but let's look at a different option.\n\nWe can put the common bits into a shared template that's stored in the themes/zafta/layouts/partials/ directory.\n\n### Create the Header and Footer Partials\n\nIn Hugo, a partial is a sugar-coated template. Normally a template reference has a path specified. Partials are different. Hugo searches for them along a TODO defined search path. This makes it easier for end-users to override the theme's presentation.\n\n```\n$ vi themes/zafta/layouts/partials/header.html\n\u003c!DOCTYPE html\u003e\n\u003chtml\u003e\n\u003chead\u003e\n\t\u003ctitle\u003e{{ .Title }}\u003c/title\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n:wq\n\n$ vi themes/zafta/layouts/partials/footer.html\n\u003c/body\u003e\n\u003c/html\u003e\n:wq\n```\n\n### Update the Home Page Template to Use the Partials\n\nThe most noticeable difference between a template call and a partials call is the lack of path:\n\n```\n{{ template \"theme/partials/header.html\" . }}\n```\nversus\n```\n{{ partial \"header.html\" . }}\n```\nBoth pass in the context.\n\nLet's change the home page template to use these new partials.\n\n```\n$ vi themes/zafta/layouts/index.html\n{{ partial \"header.html\" . }}\n\n \u003ch1\u003eposts\u003c/h1\u003e\n {{ range first 10 .Data.Pages }}\n {{ if eq .Type \"post\"}}\n \u003ch2\u003e\u003ca href=\"{{ .Permalink }}\"\u003e{{ .Title }}\u003c/a\u003e\u003c/h2\u003e\n {{ end }}\n {{ end }}\n\n \u003ch1\u003epages\u003c/h1\u003e\n {{ range .Data.Pages }}\n {{ if or (eq .Type \"page\") (eq .Type \"about\") }}\n \u003ch2\u003e\u003ca href=\"{{ .Permalink }}\"\u003e{{ .Type }} - {{ .Title }} - {{ .RelPermalink }}\u003c/a\u003e\u003c/h2\u003e\n {{ end }}\n {{ end }}\n\n{{ partial \"footer.html\" . }}\n:wq\n```\n\nGenerate the web site and verify the results. The title on the home page is now \"your title here\", which comes from the \"title\" variable in the config.toml file.\n\n### Update the Default Single Template to Use the Partials\n\n```\n$ vi themes/zafta/layouts/_default/single.html\n{{ partial \"header.html\" . }}\n\n \u003ch1\u003e{{ .Title }}\u003c/h1\u003e\n {{ .Content }}\n\n{{ partial \"footer.html\" . }}\n:wq\n```\n\nGenerate the web site and verify the results. The title on the posts and the about page should both reflect the value in the markdown file.\n\n## Add “Date Published” to Posts\n\nIt's common to have posts display the date that they were written or published, so let's add that. The front matter of our posts has a variable named \"date.\" It's usually the date the content was created, but let's pretend that's the value we want to display.\n\n### Add “Date Published” to the Template\n\nWe'll start by updating the template used to render the posts. The template code will look like:\n\n```\n{{ .Date.Format \"Mon, Jan 2, 2006\" }}\n```\n\nPosts use the default single template, so we'll change that file.\n\n```\n$ vi themes/zafta/layouts/_default/single.html\n{{ partial \"header.html\" . }}\n\n \u003ch1\u003e{{ .Title }}\u003c/h1\u003e\n \u003ch2\u003e{{ .Date.Format \"Mon, Jan 2, 2006\" }}\u003c/h2\u003e\n {{ .Content }}\n\n{{ partial \"footer.html\" . }}\n:wq\n```\n\nGenerate the web site and verify the results. The posts now have the date displayed in them. There's a problem, though. The \"about\" page also has the date displayed.\n\nAs usual, there are a couple of ways to make the date display only on posts. We could do an \"if\" statement like we did on the home page. Another way would be to create a separate template for posts.\n\nThe \"if\" solution works for sites that have just a couple of content types. It aligns with the principle of \"code for today,\" too.\n\nLet's assume, though, that we've made our site so complex that we feel we have to create a new template type. In Hugo-speak, we're going to create a section template.\n\nLet's restore the default single template before we forget.\n\n```\n$ mkdir themes/zafta/layouts/post\n$ vi themes/zafta/layouts/_default/single.html\n{{ partial \"header.html\" . }}\n\n \u003ch1\u003e{{ .Title }}\u003c/h1\u003e\n {{ .Content }}\n\n{{ partial \"footer.html\" . }}\n:wq\n```\n\nNow we'll update the post's version of the single template. If you remember Hugo's rules, the template engine will use this version over the default.\n\n```\n$ vi themes/zafta/layouts/post/single.html\n{{ partial \"header.html\" . }}\n\n \u003ch1\u003e{{ .Title }}\u003c/h1\u003e\n \u003ch2\u003e{{ .Date.Format \"Mon, Jan 2, 2006\" }}\u003c/h2\u003e\n {{ .Content }}\n\n{{ partial \"footer.html\" . }}\n:wq\n\n```\n\nNote that we removed the date logic from the default template and put it in the post template. Generate the web site and verify the results. Posts have dates and the about page doesn't.\n\n### Don't Repeat Yourself\n\nDRY is a good design goal and Hugo does a great job supporting it. Part of the art of a good template is knowing when to add a new template and when to update an existing one. While you're figuring that out, accept that you'll be doing some refactoring. Hugo makes that easy and fast, so it's okay to delay splitting up a template.\n",
"lastmodified": "2022-12-31T01:56:53.430566995Z",
"tags": null
},
"/posts/goisforlovers": {
"title": "",
"content": "+++\ntitle = \"(Hu)go Template Primer\"\ndescription = \"\"\ntags = [\n \"go\",\n \"golang\",\n \"templates\",\n \"themes\",\n \"development\",\n]\ndate = \"2014-04-02\"\ncategories = [\n \"Development\",\n \"golang\",\n]\nmenu = \"main\"\n+++\n\nHugo uses the excellent [Go][] [html/template][gohtmltemplate] library for\nits template engine. It is an extremely lightweight engine that provides a very\nsmall amount of logic. In our experience that it is just the right amount of\nlogic to be able to create a good static website. If you have used other\ntemplate systems from different languages or frameworks you will find a lot of\nsimilarities in Go templates.\n\nThis document is a brief primer on using Go templates. The [Go docs][gohtmltemplate]\nprovide more details.\n\n## Introduction to Go Templates\n\nGo templates provide an extremely simple template language. It adheres to the\nbelief that only the most basic of logic belongs in the template or view layer.\nOne consequence of this simplicity is that Go templates parse very quickly.\n\nA unique characteristic of Go templates is they are content aware. Variables and\ncontent will be sanitized depending on the context of where they are used. More\ndetails can be found in the [Go docs][gohtmltemplate].\n\n## Basic Syntax\n\nGolang templates are HTML files with the addition of variables and\nfunctions.\n\n**Go variables and functions are accessible within {{ }}**\n\nAccessing a predefined variable \"foo\":\n\n {{ foo }}\n\n**Parameters are separated using spaces**\n\nCalling the add function with input of 1, 2:\n\n {{ add 1 2 }}\n\n**Methods and fields are accessed via dot notation**\n\nAccessing the Page Parameter \"bar\"\n\n {{ .Params.bar }}\n\n**Parentheses can be used to group items together**\n\n {{ if or (isset .Params \"alt\") (isset .Params \"caption\") }} Caption {{ end }}\n\n\n## Variables\n\nEach Go template has a struct (object) made available to it. In hugo each\ntemplate is passed either a page or a node struct depending on which type of\npage you are rendering. More details are available on the\n[variables](/layout/variables) page.\n\nA variable is accessed by referencing the variable name.\n\n \u003ctitle\u003e{{ .Title }}\u003c/title\u003e\n\nVariables can also be defined and referenced.\n\n {{ $address := \"123 Main St.\"}}\n {{ $address }}\n\n\n## Functions\n\nGo template ship with a few functions which provide basic functionality. The Go\ntemplate system also provides a mechanism for applications to extend the\navailable functions with their own. [Hugo template\nfunctions](/layout/functions) provide some additional functionality we believe\nare useful for building websites. Functions are called by using their name\nfollowed by the required parameters separated by spaces. Template\nfunctions cannot be added without recompiling hugo.\n\n**Example:**\n\n {{ add 1 2 }}\n\n## Includes\n\nWhen including another template you will pass to it the data it will be\nable to access. To pass along the current context please remember to\ninclude a trailing dot. The templates location will always be starting at\nthe /layout/ directory within Hugo.\n\n**Example:**\n\n {{ template \"chrome/header.html\" . }}\n\n\n## Logic\n\nGo templates provide the most basic iteration and conditional logic.\n\n### Iteration\n\nJust like in Go, the Go templates make heavy use of range to iterate over\na map, array or slice. The following are different examples of how to use\nrange.\n\n**Example 1: Using Context**\n\n {{ range array }}\n {{ . }}\n {{ end }}\n\n**Example 2: Declaring value variable name**\n\n {{range $element := array}}\n {{ $element }}\n {{ end }}\n\n**Example 2: Declaring key and value variable name**\n\n {{range $index, $element := array}}\n {{ $index }}\n {{ $element }}\n {{ end }}\n\n### Conditionals\n\nIf, else, with, or, \u0026 and provide the framework for handling conditional\nlogic in Go Templates. Like range, each statement is closed with `end`.\n\n\nGo Templates treat the following values as false:\n\n* false\n* 0\n* any array, slice, map, or string of length zero\n\n**Example 1: If**\n\n {{ if isset .Params \"title\" }}\u003ch4\u003e{{ index .Params \"title\" }}\u003c/h4\u003e{{ end }}\n\n**Example 2: If -\u003e Else**\n\n {{ if isset .Params \"alt\" }}\n {{ index .Params \"alt\" }}\n {{else}}\n {{ index .Params \"caption\" }}\n {{ end }}\n\n**Example 3: And \u0026 Or**\n\n {{ if and (or (isset .Params \"title\") (isset .Params \"caption\")) (isset .Params \"attr\")}}\n\n**Example 4: With**\n\nAn alternative way of writing \"if\" and then referencing the same value\nis to use \"with\" instead. With rebinds the context `.` within its scope,\nand skips the block if the variable is absent.\n\nThe first example above could be simplified as:\n\n {{ with .Params.title }}\u003ch4\u003e{{ . }}\u003c/h4\u003e{{ end }}\n\n**Example 5: If -\u003e Else If**\n\n {{ if isset .Params \"alt\" }}\n {{ index .Params \"alt\" }}\n {{ else if isset .Params \"caption\" }}\n {{ index .Params \"caption\" }}\n {{ end }}\n\n## Pipes\n\nOne of the most powerful components of Go templates is the ability to\nstack actions one after another. This is done by using pipes. Borrowed\nfrom unix pipes, the concept is simple, each pipeline's output becomes the\ninput of the following pipe.\n\nBecause of the very simple syntax of Go templates, the pipe is essential\nto being able to chain together function calls. One limitation of the\npipes is that they only can work with a single value and that value\nbecomes the last parameter of the next pipeline.\n\nA few simple examples should help convey how to use the pipe.\n\n**Example 1 :**\n\n {{ if eq 1 1 }} Same {{ end }}\n\nis the same as\n\n {{ eq 1 1 | if }} Same {{ end }}\n\nIt does look odd to place the if at the end, but it does provide a good\nillustration of how to use the pipes.\n\n**Example 2 :**\n\n {{ index .Params \"disqus_url\" | html }}\n\nAccess the page parameter called \"disqus_url\" and escape the HTML.\n\n**Example 3 :**\n\n {{ if or (or (isset .Params \"title\") (isset .Params \"caption\")) (isset .Params \"attr\")}}\n Stuff Here\n {{ end }}\n\nCould be rewritten as\n\n {{ isset .Params \"caption\" | or isset .Params \"title\" | or isset .Params \"attr\" | if }}\n Stuff Here\n {{ end }}\n\n\n## Context (aka. the dot)\n\nThe most easily overlooked concept to understand about Go templates is that {{ . }}\nalways refers to the current context. In the top level of your template this\nwill be the data set made available to it. Inside of a iteration it will have\nthe value of the current item. When inside of a loop the context has changed. .\nwill no longer refer to the data available to the entire page. If you need to\naccess this from within the loop you will likely want to set it to a variable\ninstead of depending on the context.\n\n**Example:**\n\n {{ $title := .Site.Params.Title }}\n {{ range .Params.tags }}\n \u003cli\u003e \u003ca href=\"{{ $baseurl }}/tags/{{ . | urlize }}\"\u003e{{ . }}\u003c/a\u003e - {{ $title }} \u003c/li\u003e\n {{ end }}\n\nNotice how once we have entered the loop the value of {{ . }} has changed. We\nhave defined a variable outside of the loop so we have access to it from within\nthe loop.\n\n# Hugo Parameters\n\nHugo provides the option of passing values to the template language\nthrough the site configuration (for sitewide values), or through the meta\ndata of each specific piece of content. You can define any values of any\ntype (supported by your front matter/config format) and use them however\nyou want to inside of your templates.\n\n\n## Using Content (page) Parameters\n\nIn each piece of content you can provide variables to be used by the\ntemplates. This happens in the [front matter](/content/front-matter).\n\nAn example of this is used in this documentation site. Most of the pages\nbenefit from having the table of contents provided. Sometimes the TOC just\ndoesn't make a lot of sense. We've defined a variable in our front matter\nof some pages to turn off the TOC from being displayed.\n\nHere is the example front matter:\n\n```\n---\ntitle: \"Permalinks\"\ndate: \"2013-11-18\"\naliases:\n - \"/doc/permalinks/\"\ngroups: [\"extras\"]\ngroups_weight: 30\nnotoc: true\n---\n```\n\nHere is the corresponding code inside of the template:\n\n {{ if not .Params.notoc }}\n \u003cdiv id=\"toc\" class=\"well col-md-4 col-sm-6\"\u003e\n {{ .TableOfContents }}\n \u003c/div\u003e\n {{ end }}\n\n\n\n## Using Site (config) Parameters\nIn your top-level configuration file (eg, `config.yaml`) you can define site\nparameters, which are values which will be available to you in chrome.\n\nFor instance, you might declare:\n\n```yaml\nparams:\n CopyrightHTML: \"Copyright \u0026#xA9; 2013 John Doe. All Rights Reserved.\"\n TwitterUser: \"spf13\"\n SidebarRecentLimit: 5\n```\n\nWithin a footer layout, you might then declare a `\u003cfooter\u003e` which is only\nprovided if the `CopyrightHTML` parameter is provided, and if it is given,\nyou would declare it to be HTML-safe, so that the HTML entity is not escaped\nagain. This would let you easily update just your top-level config file each\nJanuary 1st, instead of hunting through your templates.\n\n```\n{{if .Site.Params.CopyrightHTML}}\u003cfooter\u003e\n\u003cdiv class=\"text-center\"\u003e{{.Site.Params.CopyrightHTML | safeHtml}}\u003c/div\u003e\n\u003c/footer\u003e{{end}}\n```\n\nAn alternative way of writing the \"if\" and then referencing the same value\nis to use \"with\" instead. With rebinds the context `.` within its scope,\nand skips the block if the variable is absent:\n\n```\n{{with .Site.Params.TwitterUser}}\u003cspan class=\"twitter\"\u003e\n\u003ca href=\"https://twitter.com/{{.}}\" rel=\"author\"\u003e\n\u003cimg src=\"/images/twitter.png\" width=\"48\" height=\"48\" title=\"Twitter: {{.}}\"\n alt=\"Twitter\"\u003e\u003c/a\u003e\n\u003c/span\u003e{{end}}\n```\n\nFinally, if you want to pull \"magic constants\" out of your layouts, you can do\nso, such as in this example:\n\n```\n\u003cnav class=\"recent\"\u003e\n \u003ch1\u003eRecent Posts\u003c/h1\u003e\n \u003cul\u003e{{range first .Site.Params.SidebarRecentLimit .Site.Recent}}\n \u003cli\u003e\u003ca href=\"{{.RelPermalink}}\"\u003e{{.Title}}\u003c/a\u003e\u003c/li\u003e\n {{end}}\u003c/ul\u003e\n\u003c/nav\u003e\n```\n\n\n[go]: https://golang.org/\n[gohtmltemplate]: https://golang.org/pkg/html/template/\n",
"lastmodified": "2022-12-31T01:56:53.430566995Z",
"tags": null
},
"/posts/hugoisforlovers": {
"title": "",
"content": "+++\ntitle = \"Getting Started with Hugo\"\ndescription = \"\"\ntags = [\n \"go\",\n \"golang\",\n \"hugo\",\n \"development\",\n]\ndate = \"2014-04-02\"\ncategories = [\n \"Development\",\n \"golang\",\n]\nmenu = \"main\"\n+++\n\n## Step 1. Install Hugo\n\nGo to [Hugo releases](https://github.com/spf13/hugo/releases) and download the\nappropriate version for your OS and architecture.\n\nSave it somewhere specific as we will be using it in the next step.\n\nMore complete instructions are available at [Install Hugo](https://gohugo.io/getting-started/installing/)\n\n## Step 2. Build the Docs\n\nHugo has its own example site which happens to also be the documentation site\nyou are reading right now.\n\nFollow the following steps:\n\n 1. Clone the [Hugo repository](http://github.com/spf13/hugo)\n 2. Go into the repo\n 3. Run hugo in server mode and build the docs\n 4. Open your browser to http://localhost:1313\n\nCorresponding pseudo commands:\n\n git clone https://github.com/spf13/hugo\n cd hugo\n /path/to/where/you/installed/hugo server --source=./docs\n \u003e 29 pages created\n \u003e 0 tags index created\n \u003e in 27 ms\n \u003e Web Server is available at http://localhost:1313\n \u003e Press ctrl+c to stop\n\nOnce you've gotten here, follow along the rest of this page on your local build.\n\n## Step 3. Change the docs site\n\nStop the Hugo process by hitting Ctrl+C.\n\nNow we are going to run hugo again, but this time with hugo in watch mode.\n\n /path/to/hugo/from/step/1/hugo server --source=./docs --watch\n \u003e 29 pages created\n \u003e 0 tags index created\n \u003e in 27 ms\n \u003e Web Server is available at http://localhost:1313\n \u003e Watching for changes in /Users/spf13/Code/hugo/docs/content\n \u003e Press ctrl+c to stop\n\n\nOpen your [favorite editor](http://vim.spf13.com) and change one of the source\ncontent pages. How about changing this very file to *fix the typo*. How about changing this very file to *fix the typo*.\n\nContent files are found in `docs/content/`. Unless otherwise specified, files\nare located at the same relative location as the url, in our case\n`docs/content/overview/quickstart.md`.\n\nChange and save this file.. Notice what happened in your terminal.\n\n \u003e Change detected, rebuilding site\n\n \u003e 29 pages created\n \u003e 0 tags index created\n \u003e in 26 ms\n\nRefresh the browser and observe that the typo is now fixed.\n\nNotice how quick that was. Try to refresh the site before it's finished building. I double dare you.\nHaving nearly instant feedback enables you to have your creativity flow without waiting for long builds.\n\n## Step 4. Have fun\n\nThe best way to learn something is to play with it.\n",
"lastmodified": "2022-12-31T01:56:53.434566978Z",
"tags": null
},
"/posts/migrate-from-jekyll": {
"title": "Migrate to Hugo from Jekyll",
"content": "\n## Move static content to `static`\nJekyll has a rule that any directory not starting with `_` will be copied as-is to the `_site` output. Hugo keeps all static content under `static`. You should therefore move it all there.\nWith Jekyll, something that looked like\n\n ▾ \u003croot\u003e/\n ▾ images/\n logo.png\n\nshould become\n\n ▾ \u003croot\u003e/\n ▾ static/\n ▾ images/\n logo.png\n\nAdditionally, you'll want any files that should reside at the root (such as `CNAME`) to be moved to `static`.\n\n## Create your Hugo configuration file\nHugo can read your configuration as JSON, YAML or TOML. Hugo supports parameters custom configuration too. Refer to the [Hugo configuration documentation](/overview/configuration/) for details.\n\n## Set your configuration publish folder to `_site`\nThe default is for Jekyll to publish to `_site` and for Hugo to publish to `public`. If, like me, you have [`_site` mapped to a git submodule on the `gh-pages` branch](http://blog.blindgaenger.net/generate_github_pages_in_a_submodule.html), you'll want to do one of two alternatives:\n\n1. Change your submodule to point to map `gh-pages` to public instead of `_site` (recommended).\n\n git submodule deinit _site\n git rm _site\n git submodule add -b gh-pages git@github.com:your-username/your-repo.git public\n\n2. Or, change the Hugo configuration to use `_site` instead of `public`.\n\n {\n ..\n \"publishdir\": \"_site\",\n ..\n }\n\n## Convert Jekyll templates to Hugo templates\nThat's the bulk of the work right here. The documentation is your friend. You should refer to [Jekyll's template documentation](http://jekyllrb.com/docs/templates/) if you need to refresh your memory on how you built your blog and [Hugo's template](/layout/templates/) to learn Hugo's way.\n\nAs a single reference data point, converting my templates for [heyitsalex.net](http://heyitsalex.net/) took me no more than a few hours.\n\n## Convert Jekyll plugins to Hugo shortcodes\nJekyll has [plugins](http://jekyllrb.com/docs/plugins/); Hugo has [shortcodes](/doc/shortcodes/). It's fairly trivial to do a port.\n\n### Implementation\nAs an example, I was using a custom [`image_tag`](https://github.com/alexandre-normand/alexandre-normand/blob/74bb12036a71334fdb7dba84e073382fc06908ec/_plugins/image_tag.rb) plugin to generate figures with caption when running Jekyll. As I read about shortcodes, I found Hugo had a nice built-in shortcode that does exactly the same thing.\n\nJekyll's plugin:\n\n module Jekyll\n class ImageTag \u003c Liquid::Tag\n @url = nil\n @caption = nil\n @class = nil\n @link = nil\n // Patterns\n IMAGE_URL_WITH_CLASS_AND_CAPTION =\n IMAGE_URL_WITH_CLASS_AND_CAPTION_AND_LINK = /(\\w+)(\\s+)((https?:\\/\\/|\\/)(\\S+))(\\s+)\"(.*?)\"(\\s+)-\u003e((https?:\\/\\/|\\/)(\\S+))(\\s*)/i\n IMAGE_URL_WITH_CAPTION = /((https?:\\/\\/|\\/)(\\S+))(\\s+)\"(.*?)\"/i\n IMAGE_URL_WITH_CLASS = /(\\w+)(\\s+)((https?:\\/\\/|\\/)(\\S+))/i\n IMAGE_URL = /((https?:\\/\\/|\\/)(\\S+))/i\n def initialize(tag_name, markup, tokens)\n super\n if markup =~ IMAGE_URL_WITH_CLASS_AND_CAPTION_AND_LINK\n @class = $1\n @url = $3\n @caption = $7\n @link = $9\n elsif markup =~ IMAGE_URL_WITH_CLASS_AND_CAPTION\n @class = $1\n @url = $3\n @caption = $7\n elsif markup =~ IMAGE_URL_WITH_CAPTION\n @url = $1\n @caption = $5\n elsif markup =~ IMAGE_URL_WITH_CLASS\n @class = $1\n @url = $3\n elsif markup =~ IMAGE_URL\n @url = $1\n end\n end\n def render(context)\n if @class\n source = \"\u003cfigure class='#{@class}'\u003e\"\n else\n source = \"\u003cfigure\u003e\"\n end\n if @link\n source += \"\u003ca href=\\\"#{@link}\\\"\u003e\"\n end\n source += \"\u003cimg src=\\\"#{@url}\\\"\u003e\"\n if @link\n source += \"\u003c/a\u003e\"\n end\n source += \"\u003cfigcaption\u003e#{@caption}\u003c/figcaption\u003e\" if @caption\n source += \"\u003c/figure\u003e\"\n source\n end\n end\n end\n Liquid::Template.register_tag('image', Jekyll::ImageTag)\n\nis written as this Hugo shortcode:\n\n \u003c!-- image --\u003e\n \u003cfigure {{ with .Get \"class\" }}class=\"{{.}}\"{{ end }}\u003e\n {{ with .Get \"link\"}}\u003ca href=\"{{.}}\"\u003e{{ end }}\n \u003cimg src=\"{{ .Get \"src\" }}\" {{ if or (.Get \"alt\") (.Get \"caption\") }}alt=\"{{ with .Get \"alt\"}}{{.}}{{else}}{{ .Get \"caption\" }}{{ end }}\"{{ end }} /\u003e\n {{ if .Get \"link\"}}\u003c/a\u003e{{ end }}\n {{ if or (or (.Get \"title\") (.Get \"caption\")) (.Get \"attr\")}}\n \u003cfigcaption\u003e{{ if isset .Params \"title\" }}\n {{ .Get \"title\" }}{{ end }}\n {{ if or (.Get \"caption\") (.Get \"attr\")}}\u003cp\u003e\n {{ .Get \"caption\" }}\n {{ with .Get \"attrlink\"}}\u003ca href=\"{{.}}\"\u003e {{ end }}\n {{ .Get \"attr\" }}\n {{ if .Get \"attrlink\"}}\u003c/a\u003e {{ end }}\n \u003c/p\u003e {{ end }}\n \u003c/figcaption\u003e\n {{ end }}\n \u003c/figure\u003e\n \u003c!-- image --\u003e\n\n### Usage\nI simply changed:\n\n {% image full http://farm5.staticflickr.com/4136/4829260124_57712e570a_o_d.jpg \"One of my favorite touristy-type photos. I secretly waited for the good light while we were \"having fun\" and took this. Only regret: a stupid pole in the top-left corner of the frame I had to clumsily get rid of at post-processing.\" -\u003ehttp://www.flickr.com/photos/alexnormand/4829260124/in/set-72157624547713078/ %}\n\nto this (this example uses a slightly extended version named `fig`, different than the built-in `figure`):\n\n {{%/* fig class=\"full\" src=\"http://farm5.staticflickr.com/4136/4829260124_57712e570a_o_d.jpg\" title=\"One of my favorite touristy-type photos. I secretly waited for the good light while we were having fun and took this. Only regret: a stupid pole in the top-left corner of the frame I had to clumsily get rid of at post-processing.\" link=\"http://www.flickr.com/photos/alexnormand/4829260124/in/set-72157624547713078/\" */%}}\n\nAs a bonus, the shortcode named parameters are, arguably, more readable.\n\n## Finishing touches\n### Fix content\nDepending on the amount of customization that was done with each post with Jekyll, this step will require more or less effort. There are no hard and fast rules here except that `hugo server --watch` is your friend. Test your changes and fix errors as needed.\n\n### Clean up\nYou'll want to remove the Jekyll configuration at this point. If you have anything else that isn't used, delete it.\n\n## A practical example in a diff\n[Hey, it's Alex](http://heyitsalex.net/) was migrated in less than a _father-with-kids day_ from Jekyll to Hugo. You can see all the changes (and screw-ups) by looking at this [diff](https://github.com/alexandre-normand/alexandre-normand/compare/869d69435bd2665c3fbf5b5c78d4c22759d7613a...b7f6605b1265e83b4b81495423294208cc74d610).\n",
"lastmodified": "2022-12-31T01:56:53.434566978Z",
"tags": null
}
}
Reference in New Issue View Git Blame Copy Permalink