diff --git a/exampleSite/content/docs/getting-started.md b/exampleSite/content/docs/getting-started.md index d4271f8..16ee23f 100644 --- a/exampleSite/content/docs/getting-started.md +++ b/exampleSite/content/docs/getting-started.md @@ -14,6 +14,7 @@ You will be able to quickly get started by using the above template repository. We have provided a [GitHub Actions workflow](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow) which can help automatically build and deploy your site to GitHub Pages, and host it for free. +For more options, check out [Deploy Site](../guide/deploy-site). [🌐 Demo ↗](https://imfing.github.io/hextra-starter-template/) diff --git a/exampleSite/content/docs/guide/_index.md b/exampleSite/content/docs/guide/_index.md index 65c92bb..2fd2a3f 100644 --- a/exampleSite/content/docs/guide/_index.md +++ b/exampleSite/content/docs/guide/_index.md @@ -7,7 +7,7 @@ sidebar: open: true --- -Explore the following sections to learn to compose content using Hextra: +Explore the following sections to learn how to use Hextra: @@ -19,4 +19,5 @@ Explore the following sections to learn to compose content using Hextra: {{< card link="latex" title="LaTeX" icon="variable" >}} {{< card link="diagrams" title="Diagrams" icon="chart-square-bar" >}} {{< card link="shortcodes" title="Shortcodes" icon="template" >}} + {{< card link="deploy-site" title="Deploy Site" icon="server" >}} {{< /cards >}} diff --git a/exampleSite/content/docs/guide/deploy-site.md b/exampleSite/content/docs/guide/deploy-site.md new file mode 100644 index 0000000..fdf9bcb --- /dev/null +++ b/exampleSite/content/docs/guide/deploy-site.md @@ -0,0 +1,163 @@ +--- +title: Deploy Site +prev: /docs/guide/shortcodes +next: /docs/advanced +--- + +Hugo generates static websites, allowing for flexible hosting options. +This page provides guides for deploying your Hextra site on various platforms. + + + + +## GitHub Pages + +[GitHub Pages](https://docs.github.com/pages) is the recommended way to deploy and host your website for free. + +If you bootstrap the site using [hextra-starter-template][hextra-starter-template], it has provided GitHub Actions workflow out-of-the-box that helps automatically deploy to GitHub Pages. + +{{% details title="GitHub Actions Configuration" closed="true" %}} + +Below is an example configuration from [hextra-starter-template][hextra-starter-template]: + +```yaml {filename=".github/workflows/pages.yaml"} +# Sample workflow for building and deploying a Hugo site to GitHub Pages +name: Deploy Hugo site to Pages + +on: + # Runs on pushes targeting the default branch + push: + branches: ["main"] + + # Allows you to run this workflow manually from the Actions tab + workflow_dispatch: + +# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages +permissions: + contents: read + pages: write + id-token: write + +# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. +# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. +concurrency: + group: "pages" + cancel-in-progress: false + +# Default to bash +defaults: + run: + shell: bash + +jobs: + # Build job + build: + runs-on: ubuntu-latest + env: + HUGO_VERSION: 0.117.0 + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + fetch-depth: 0 # Fetch all history for .GitInfo and .Lastmod + - name: Setup Go + uses: actions/setup-go@v4 + with: + go-version: '1.21' + - name: Setup Hugo + uses: peaceiris/actions-hugo@v2 + with: + hugo-version: '0.117.0' + extended: true + - name: Build with Hugo + env: + # For maximum backward compatibility with Hugo modules + HUGO_ENVIRONMENT: production + HUGO_ENV: production + run: | + hugo \ + --gc --minify \ + --baseURL "https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/" + - name: Upload artifact + uses: actions/upload-pages-artifact@v2 + with: + path: ./public + + # Deployment job + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + needs: build + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v2 +``` + +{{% /details %}} + + +{{< callout >}} + In your repository settings, set the **Pages** > **Build and deployment** > **Source** to **GitHub Actions**: + ![](https://user-images.githubusercontent.com/5097752/266784808-99676430-884e-42ab-b901-f6534a0d6eee.png) +{{< /callout >}} + +By default, the above GitHub Actions workflow assumes that the site is deploying to `https://.github.io//`. + +If you are deploying to `https://.github.io/` then modify the `--baseURL`: + +```yaml {filename=".github/workflows/pages.yaml",linenos=table,linenostart=54,hl_lines=[4]} +run: | + hugo \ + --gc --minify \ + --baseURL "https://${{ github.repository_owner }}.github.io/" +``` + +If you are deploying to your own domain, please change the `--baseURL` value accordingly. + + +## Cloudflare Pages + +1. Put your site source code in a Git repository (e.g. GitHub) +2. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account +3. In Account Home, select **Workers & Pages** > **Create application** > **Pages** > **Connect to Git** +4. Select the repository, and in the **Set up builds and deployments** section, provide the following information: + +| Configuration | Value | +| ----------------- | -------------------- | +| Production branch | `main` | +| Build command | `hugo --gc --minify` | +| Build directory | `public` | + +For more details, check out: +- [Deploy a Hugo site](https://developers.cloudflare.com/pages/framework-guides/deploy-a-hugo-site/#deploy-with-cloudflare-pages). +- [Language support and tools](https://developers.cloudflare.com/pages/platform/language-support-and-tools/). + + +## Netlify + +1. Push your code to your Git repository (GitHub, GitLab, etc.) +2. [Import the project](https://app.netlify.com/start) to Netlify +3. If you are not using [hextra-starter-template][hextra-starter-template], configure the following manually: + - Configure the Build command to `hugo --gc --minify` + - Specify the Publish directory to `public` + - Add Environment variable `HUGO_VERSION` and set to `0.119.0` +4. Deploy! + +Check [Hugo on Netlify](https://docs.netlify.com/integrations/frameworks/hugo/) for more details. + + +## Vercel + +1. Push your code to your Git repository (GitHub, GitLab, etc.) +2. Go to [Vercel Dashboard](https://vercel.com/dashboard) and import your Hugo project +3. Configure the project, select Hugo as Framework Preset +4. Override the Build Command and Install command: + 1. Set Build Command to `hugo --gc --minify` + 2. Set Install Command to `yum install golang` + +![image](https://github.com/imfing/hextra/assets/5097752/887d949b-8d05-413f-a2b4-7ab92192d0b3) + +[hextra-starter-template]: https://github.com/imfing/hextra-starter-template diff --git a/exampleSite/content/docs/guide/shortcodes/tabs.md b/exampleSite/content/docs/guide/shortcodes/tabs.md index 66ba685..c63547a 100644 --- a/exampleSite/content/docs/guide/shortcodes/tabs.md +++ b/exampleSite/content/docs/guide/shortcodes/tabs.md @@ -1,6 +1,6 @@ --- title: Tabs -next: /docs/advanced/ +next: /docs/guide/deploy-site --- ## Example