ar.falsy.cat/notes/hosting/index.html

62 lines
19 KiB
HTML
Raw Normal View History

<!doctype html><html lang=en><head><meta charset=utf-8><meta name=description content="Hosting on GitHub Pages Quartz is designed to be effortless to deploy. If you forked and cloned Quartz directly from the repository, everything should already be good to go!"><meta property="og:title" content="Deploying Quartz to the Web"><meta property="og:description" content="Hosting on GitHub Pages Quartz is designed to be effortless to deploy. If you forked and cloned Quartz directly from the repository, everything should already be good to go!"><meta property="og:type" content="website"><meta property="og:image" content="https://ar.falsy.cat/icon.png"><meta property="og:url" content="https://ar.falsy.cat/notes/hosting/"><meta property="og:width" content="200"><meta property="og:height" content="200"><meta name=twitter:card content="summary"><meta name=twitter:title content="Deploying Quartz to the Web"><meta name=twitter:description content="Hosting on GitHub Pages Quartz is designed to be effortless to deploy. If you forked and cloned Quartz directly from the repository, everything should already be good to go!"><meta name=twitter:image content="https://ar.falsy.cat/icon.png"><meta name=twitter:site content="_jzhao"><title>Deploying Quartz to the Web</title><meta name=viewport content="width=device-width,initial-scale=1"><link rel="shortcut icon" type=image/png href=https://ar.falsy.cat//icon.png><link href=https://ar.falsy.cat/styles.b369a84b3c6e6bfd686ad1f9da65641c.min.css rel=stylesheet><link href=https://ar.falsy.cat/styles/_light_syntax.86a48a52faebeaaf42158b72922b1c90.min.css rel=stylesheet id=theme-link><script src=https://ar.falsy.cat/js/darkmode.557cde7fcc3511a3d7ca8545ecd46d77.min.js></script>
<script src=https://ar.falsy.cat/js/util.a0ccf91e1937fe761a74da4946452710.min.js></script>
<link rel=preload href=https://cdn.jsdelivr.net/npm/katex@0.15.1/dist/katex.min.css as=style onload='this.onload=null,this.rel="stylesheet"' integrity=sha384-R4558gYOUz8mP9YWpZJjofhk+zx0AS11p36HnD2ZKj/6JR5z27gSSULCNHIRReVs crossorigin=anonymous><script defer src=https://cdn.jsdelivr.net/npm/katex@0.15.1/dist/katex.min.js integrity=sha384-z1fJDqw8ZApjGO3/unPWUPsIymfsJmyrDVWC8Tv/a1HeOtGmkwNd/7xUS0Xcnvsx crossorigin=anonymous></script>
<script defer src=https://cdn.jsdelivr.net/npm/katex@0.15.1/dist/contrib/auto-render.min.js integrity=sha384-+XBljXPPiv+OzfbB3cVmLHf4hdUFHlWNZN5spNQ7rmHTXpd7WvJum6fIACpNNfIR crossorigin=anonymous></script>
<script defer src=https://cdn.jsdelivr.net/npm/katex@0.16.2/dist/contrib/copy-tex.min.js integrity=sha384-ww/583aHhxWkz5DEVn6OKtNiIaLi2iBRNZXfJRiY1Ai7tnJ9UXpEsyvOITVpTl4A crossorigin=anonymous></script>
<script async src=https://unpkg.com/@floating-ui/core@0.7.3></script>
<script async src=https://unpkg.com/@floating-ui/dom@0.5.4></script>
<script async src=https://ar.falsy.cat/js/popover.aa9bc99c7c38d3ae9538f218f1416adb.min.js></script>
<script defer src=https://ar.falsy.cat/js/code-title.ce4a43f09239a9efb48fee342e8ef2df.min.js></script>
<script defer src=https://ar.falsy.cat/js/clipboard.2913da76d3cb21c5deaa4bae7da38c9f.min.js></script>
<script defer src=https://ar.falsy.cat/js/callouts.7723cac461d613d118ee8bb8216b9838.min.js></script>
<script>const SEARCH_ENABLED=!1,LATEX_ENABLED=!0,PRODUCTION=!0,BASE_URL="https://ar.falsy.cat/",fetchData=Promise.all([fetch("https://ar.falsy.cat/indices/linkIndex.5527d50d14f23ac29fce778fdc24df51.min.json").then(e=>e.json()).then(e=>({index:e.index,links:e.links})),fetch("https://ar.falsy.cat/indices/contentIndex.8feb5914155c97a9b8a1454caf733b20.min.json").then(e=>e.json())]).then(([{index:e,links:t},n])=>({index:e,links:t,content:n})),render=()=>{const e=new URL(BASE_URL),t=e.pathname,n=window.location.pathname,s=t==n;addCopyButtons(),addTitleToCodeBlocks(),addCollapsibleCallouts(),initPopover("https://ar.falsy.cat",!0);const o=document.getElementById("footer");if(o){const e=document.getElementById("graph-container");if(!e)return requestAnimationFrame(render);e.textContent="";const t=s&&!1;drawGraph("https://ar.falsy.cat",t,[{"/moc":"#4388cc"}],t?{centerForce:1,depth:-1,enableDrag:!0,enableLegend:!1,enableZoom:!0,fontSize:.5,linkDistance:1,opacityScale:3,repelForce:1,scale:1.4}:{centerForce:1,depth:1,enableDrag:!0,enableLegend:!1,enableZoom:!0,fontSize:.6,linkDistance:1,opacityScale:3,repelForce:2,scale:1.2})}var i=document.getElementsByClassName("mermaid");i.length>0&&import("https://unpkg.com/mermaid@9/dist/mermaid.esm.min.mjs").then(e=>{e.default.init()});function a(n){const e=n.target,t=e.className.split(" "),s=t.includes("broken"),o=t.includes("internal-link");plausible("Link Click",{props:{href:e.href,broken:s,internal:o,graph:!1}})}const r=document.querySelectorAll("a");for(link of r)link.className.includes("root-title")&&link.addEventListener("click",a,{once:!0})},init=(e=document)=>{addCopyButtons(),addTitleToCodeBlocks(),renderMathInElement(e.body,{delimiters:[{left:"$$",right:"$$",display:!0},{left:"$",right:"$",display:!1}],macros:{'':"'"},throwOnError:!1})}</script><script type=module>
import { attachSPARouting } from "https:\/\/ar.falsy.cat\/js\/router.d6fe6bd821db9ea97f9aeefae814d8e7.min.js"
attachSPARouting(init, render)
</script><script defer data-domain=ar.falsy.cat src=https://plausible.io/js/script.js></script>
<script>window.plausible=window.plausible||function(){(window.plausible.q=window.plausible.q||[]).push(arguments)}</script></head><body><div id=search-container><div id=search-space><input autocomplete=off id=search-bar name=search type=text aria-label=Search placeholder="Search for something..."><div id=results-container></div></div></div><script src=https://cdn.jsdelivr.net/npm/flexsearch@0.7.21/dist/flexsearch.bundle.js integrity="sha256-i3A0NZGkhsKjVMzFxv3ksk0DZh3aXqu0l49Bbh0MdjE=" crossorigin=anonymous defer></script>
<script defer src=https://ar.falsy.cat/js/full-text-search.e6e2e0c213187ca0c703d6e2c7a77fcd.min.js></script><div class=singlePage><header><h1 id=page-title><a class=root-title href=https://ar.falsy.cat/>🪴 Quartz 3.3</a></h1><div class=spacer></div><div id=search-icon><p>Search</p><svg tabindex="0" aria-labelledby="title desc" role="img" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 19.9 19.7"><title id="title">Search Icon</title><desc id="desc">Icon to open search</desc><g class="search-path" fill="none"><path stroke-linecap="square" d="M18.5 18.3l-5.4-5.4"/><circle cx="8" cy="8" r="7"/></g></svg></div><div class=darkmode><input class=toggle id=darkmode-toggle type=checkbox tabindex=-1>
<label id=toggle-label-light for=darkmode-toggle tabindex=-1><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" id="dayIcon" viewBox="0 0 35 35" style="enable-background:new 0 0 35 35"><title>Light Mode</title><path d="M6 17.5C6 16.672 5.328 16 4.5 16h-3C.672 16 0 16.672.0 17.5S.672 19 1.5 19h3C5.328 19 6 18.328 6 17.5zM7.5 26c-.414.0-.789.168-1.061.439l-2 2C4.168 28.711 4 29.086 4 29.5 4 30.328 4.671 31 5.5 31c.414.0.789-.168 1.06-.44l2-2C8.832 28.289 9 27.914 9 27.5 9 26.672 8.329 26 7.5 26zm10-20C18.329 6 19 5.328 19 4.5v-3C19 .672 18.329.0 17.5.0S16 .672 16 1.5v3C16 5.328 16.671 6 17.5 6zm10 3c.414.0.789-.168 1.06-.439l2-2C30.832 6.289 31 5.914 31 5.5 31 4.672 30.329 4 29.5 4c-.414.0-.789.168-1.061.44l-2 2C26.168 6.711 26 7.086 26 7.5 26 8.328 26.671 9 27.5 9zM6.439 8.561C6.711 8.832 7.086 9 7.5 9 8.328 9 9 8.328 9 7.5c0-.414-.168-.789-.439-1.061l-2-2C6.289 4.168 5.914 4 5.5 4 4.672 4 4 4.672 4 5.5c0 .414.168.789.439 1.06l2 2.001zM33.5 16h-3c-.828.0-1.5.672-1.5 1.5s.672 1.5 1.5 1.5h3c.828.0 1.5-.672 1.5-1.5S34.328 16 33.5 16zM28.561 26.439C28.289 26.168 27.914 26 27.5 26c-.828.0-1.5.672-1.5 1.5.0.414.168.789.439 1.06l2 2C28.711 30.832 29.086 31 29.5 31c.828.0 1.5-.672 1.5-1.5.0-.414-.168-.789-.439-1.061l-2-2zM17.5 29c-.829.0-1.5.672-1.5 1.5v3c0 .828.671 1.5 1.5 1.5s1.5-.672 1.5-1.5v-3C19 29.672 18.329 29 17.5 29zm0-22C11.71 7 7 11.71 7 17.5S11.71 28 17.5 28 28 23.29 28 17.5 23.29 7 17.5 7zm0 18c-4.136.0-7.5-3.364-7.5-7.5s3.364-7.5 7.5-7.5 7.5 3.364 7.5 7.5S21.636 25 17.5 25z"/></svg></label><label id=toggle-label-dark for=darkmode-toggle tabindex=-1><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" id="nightIcon" viewBox="0 0 100 100" style="enable-background='new 0 0 100 100'"><title>Dark Mode</title><path d="M96.76 66.458c-.853-.852-2.15-1.064-3.23-.534-6.063 2.991-12.858 4.571-19.655 4.571C62.022 70.495 50.88 65.88 42.5 57.5 29.043 44.043 25.658 23.536 34.076 6.47c.532-1.08.318-2.379-.534-3.23-.851-.852-2.15-1.064-3.23-.534-4.918 2.427-9.375 5.619-13.246 9.491-9.447 9.447-14.65 22.008-14.65 35.369.0 13.36 5.203 25.921 14.65 35.368s22.008 14.65 35.368 14.65c13.361.0 25.921-5.203 35.369-14.65 3.872-3.871 7.064-8.328 9.491-13.246C97.826 68.608 97.611 67.309 96.76 66.458z"/></svg></label></div></header><article><h1>Deploying Quartz to the Web</h1><p class=meta>Last updated
Nov 20, 2022
<a href=https://github.com/jackyzha0/quartz/tree/hugo/content/notes/hosting.md rel=noopener>Edit Source</a></p><ul class=tags><li><a href=https://ar.falsy.cat/tags/setup/>Setup</a></li></ul><aside class=mainTOC><details><summary>Table of Contents</summary><nav id=TableOfContents><ol><li><a href=#hosting-on-github-pages>Hosting on GitHub Pages</a><ol><li><a href=#enable-github-actions>Enable GitHub Actions</a></li><li><a href=#enable-github-pages>Enable GitHub Pages</a></li><li><a href=#pushing-changes>Pushing Changes</a></li><li><a href=#setting-up-the-site>Setting up the Site</a></li><li><a href=#ignoring-files>Ignoring Files</a></li></ol></li><li><a href=#docker-support>Docker Support</a></li></ol></nav></details></aside><a href=#hosting-on-github-pages><h2 id=hosting-on-github-pages><span class=hanchor arialabel=Anchor># </span>Hosting on GitHub Pages</h2></a><p>Quartz 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.</p><a href=#enable-github-actions><h3 id=enable-github-actions><span class=hanchor arialabel=Anchor># </span>Enable GitHub Actions</h3></a><p>By default, GitHub disables workflows from running automatically on Forked Repostories. Head to the &lsquo;Actions&rsquo; tab of your forked repository and Enable Workflows to setup deploying your Quartz site!</p><p><img src=https://ar.falsy.cat//notes/images/github-actions.png width=auto alt="Enable GitHub Actions"><em>Enable GitHub Actions</em></p><a href=#enable-github-pages><h3 id=enable-github-pages><span class=hanchor arialabel=Anchor># </span>Enable GitHub Pages</h3></a><p>Head to the &lsquo;Settings&rsquo; tab of your forked repository and go to the &lsquo;Pages&rsquo; tab.</p><ol><li>(IMPORTANT) Set the source to deploy from <code>master</code> (and not <code>hugo</code>) using <code>/ (root)</code></li><li>Set a custom domain here if you have one!</li></ol><p><img src=https://ar.falsy.cat//notes/images/github-pages.png width=auto alt="Enable GitHub Pages"><em>Enable GitHub Pages</em></p><a href=#pushing-changes><h3 id=pushing-changes><span class=hanchor arialabel=Anchor># </span>Pushing Changes</h3></a><p>To see your changes on the internet, we need to push it them to GitHub. Quartz is a <code>git</code> repository so updating it is the same workflow as you would follow as if it were just a regular software project.</p><div class=highlight><div class=chroma><table class=lntable><tr><td class=lntd><pre tabindex=0 class=chroma><code><span class=lnt>1
</span><span class=lnt>2
</span><span class=lnt>3
</span><span class=lnt>4
</span><span class=lnt>5
</span><span class=lnt>6
</span><span class=lnt>7
</span><span class=lnt>8
</span><span class=lnt>9
</span></code></pre></td><td class=lntd><pre tabindex=0 class=chroma><code class=language-shell data-lang=shell><span class=line><span class=cl><span class=c1># Navigate to Quartz folder</span>
</span></span><span class=line><span class=cl><span class=nb>cd</span> &lt;path-to-quartz&gt;
</span></span><span class=line><span class=cl>
</span></span><span class=line><span class=cl><span class=c1># Commit all changes</span>
</span></span><span class=line><span class=cl>git add .
</span></span><span class=line><span class=cl>git commit -m <span class=s2>&#34;message describing changes&#34;</span>
</span></span><span class=line><span class=cl>
</span></span><span class=line><span class=cl><span class=c1># Push to GitHub to update site</span>
</span></span><span class=line><span class=cl>git push origin hugo
</span></span></code></pre></td></tr></table></div></div><p>Note: we specifically push to the <code>hugo</code> branch here. Our GitHub action automatically runs everytime a push to is detected to that branch and then updates the <code>master</code> branch for redeployment.</p><a href=#setting-up-the-site><h3 id=setting-up-the-site><span class=hanchor arialabel=Anchor># </span>Setting up the Site</h3></a><p>Now let&rsquo;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&rsquo;s easy too.</p><p>Here, we take advantage of GitHub&rsquo;s free page hosting to deploy our site. Change <code>baseURL</code> in <code>/config.toml</code>.</p><p>Make sure that your <code>baseURL</code> has a trailing <code>/</code>!</p><p><a href=https://github.com/jackyzha0/quartz/blob/hugo/config.toml rel=noopener>Reference <code>config.toml</code> here</a></p><div class=highlight><div class=chroma><table class=lntable><tr><td class=lntd><pre tabindex=0 class=chroma><code><span class=lnt>1
</span></code></pre></td><td class=lntd><pre tabindex=0 class=chroma><code class=language-toml data-lang=toml><span class=line><span class=cl><span class=nx>baseURL</span> <span class=p>=</span> <span class=s2>&#34;https://&lt;YOUR-DOMAIN&gt;/&#34;</span>
</span></span></code></pre></td></tr></table></div></div><p>If you are using this under a subdomain (e.g. <code>&lt;YOUR-GITHUB-USERNAME>.github.io/quartz</code>), include the trailing <code>/</code>. <strong>You need to do this especially if you are using GitHub!</strong></p><div class=highlight><div class=chroma><table class=lntable><tr><td class=lntd><pre tabindex=0 class=chroma><code><span class=lnt>1
</span></code></pre></td><td class=lntd><pre tabindex=0 class=chroma><code class=language-toml data-lang=toml><span class=line><span class=cl><span class=nx>baseURL</span> <span class=p>=</span> <span class=s2>&#34;https://&lt;YOUR-GITHUB-USERNAME&gt;.github.io/quartz/&#34;</span>
</span></span></code></pre></td></tr></table></div></div><p>Change <code>cname</code> in <code>/.github/workflows/deploy.yaml</code>. Again, if you don&rsquo;t have a custom domain to use, you can use <code>&lt;YOUR-USERNAME>.github.io</code>.</p><p>Please note that the <code>cname</code> field should <em>not</em> have any path <code>e.g. end with /quartz</code> or have a trailing <code>/</code>.</p><p><a href=https://github.com/jackyzha0/quartz/blob/hugo/.github/workflows/deploy.yaml rel=noopener>Reference <code>deploy.yaml</code> here</a></p><div class=highlight title=.github/workflows/deploy.yaml><div class=chroma><table class=lntable><tr><td class=lntd><pre tabindex=0 class=chroma><code><span class=lnt>1
</span><span class=lnt>2
</span><span class=lnt>3
</span><span class=lnt>4
</span><span class=lnt>5
</span><span class=lnt>6
</span><span class=lnt>7
</span></code></pre></td><td class=lntd><pre tabindex=0 class=chroma><code class=language-yaml data-lang=yaml><span class=line><span class=cl>- <span class=nt>name</span><span class=p>:</span><span class=w> </span><span class=l>Deploy </span><span class=w>
</span></span></span><span class=line><span class=cl><span class=w> </span><span class=nt>uses</span><span class=p>:</span><span class=w> </span><span class=l>peaceiris/actions-gh-pages@v3 </span><span class=w>
</span></span></span><span class=line><span class=cl><span class=w> </span><span class=nt>with</span><span class=p>:</span><span class=w>
</span></span></span><span class=line><span class=cl><span class=w> </span><span class=nt>github_token</span><span class=p>:</span><span class=w> </span><span class=l>${{ secrets.GITHUB_TOKEN }}</span><span class=w> </span><span class=c># this can stay as is, GitHub fills this in for us!</span><span class=w>
</span></span></span><span class=line><span class=cl><span class=w> </span><span class=nt>publish_dir</span><span class=p>:</span><span class=w> </span><span class=l>./public </span><span class=w>
</span></span></span><span class=line><span class=cl><span class=w> </span><span class=nt>publish_branch</span><span class=p>:</span><span class=w> </span><span class=l>master</span><span class=w>
</span></span></span><span class=line><span class=cl><span class=w> </span><span class=nt>cname</span><span class=p>:</span><span class=w> </span><span class=l>&lt;YOUR-DOMAIN&gt;</span><span class=w>
</span></span></span></code></pre></td></tr></table></div></div><p>Have a custom domain?
<a href=/notes/custom-Domain/ rel=noopener class=internal-link data-src=/notes/custom-Domain/>Learn how to set it up with Quartz </a>.</p><a href=#ignoring-files><h3 id=ignoring-files><span class=hanchor arialabel=Anchor># </span>Ignoring Files</h3></a><p>Only want to publish a subset of all of your notes? Don&rsquo;t worry, Quartz makes this a simple two-step process.</p><p>
<a href=/notes/ignore-notes/ rel=noopener class=internal-link data-src=/notes/ignore-notes/>Excluding pages from being published</a></p><a href=#docker-support><h2 id=docker-support><span class=hanchor arialabel=Anchor># </span>Docker Support</h2></a><p>If you don&rsquo;t want to use a hosting service, you can host using
<a href=/notes/docker/ rel=noopener class=internal-link data-src=/notes/docker/>Docker</a> instead!
I would <em>not use this method</em> unless you know what you are doing.</p><hr><p>Now that your Quartz is live, let&rsquo;s figure out how to make Quartz really <em>yours</em>!</p><blockquote><p>Step 6: 🎨
<a href=/notes/config/ rel=noopener class=internal-link data-src=/notes/config/>Customizing Quartz</a></p></blockquote><p>Having problems? Checkout our
<a href=/notes/troubleshooting/ rel=noopener class=internal-link data-src=/notes/troubleshooting/>FAQ and Troubleshooting guide</a>.</p></article><hr><div class=page-end id=footer><div class=backlinks-container><h3>Backlinks</h3><ul class=backlinks><li><a href=/notes/editing/ data-ctx="Hosting Quartz online!" data-src=/notes/editing class=internal-link>Editing Content in Quartz</a></li><li><a href=/notes/preview-changes/ data-ctx="Hosting Quartz online!" data-src=/notes/preview-changes class=internal-link>Preview Changes</a></li><li><a href=/notes/troubleshooting/ data-ctx="the hosting guide" data-src=/notes/troubleshooting class=internal-link>Troubleshooting and FAQ</a></li></ul></div><div><script async src=https://cdn.jsdelivr.net/npm/d3@6.7.0/dist/d3.min.js integrity="sha256-+7jaYCp29O1JusNWHaYtgUn6EhuP0VaFuswhNV06MyI=" crossorigin=anonymous></script><h3>Interactive Graph</h3><div id=graph-container></div><style>:root{--g-node:var(--secondary);--g-node-active:var(--primary);--g-node-inactive:var(--visited);--g-link:var(--outlinegray);--g-link-active:#5a7282}</style><script src=https://ar.falsy.cat/js/graph.6579af7b10c818dbd2ca038702db0224.js></script></div></div><div id=contact_buttons><footer><p>Made by Jacky Zhao using <a href=https://github.com/jackyzha0/quartz>Quartz</a>, © 2023</p><ul><li><a href=https://ar.falsy.cat/>Home</a></li><li><a href=https://twitter.com/_jzhao>Twitter</a></li><li><a href=https://github.com/jackyzha0>GitHub</a></li></ul></footer></div></div></body></html>