From 71f739460f43e3e1226d3b778ccd1c20c4ca9af3 Mon Sep 17 00:00:00 2001 From: Joe Mooring Date: Fri, 22 Aug 2025 11:36:45 -0700 Subject: [PATCH] content: Reformat procedures to use description lists instead of H3 elements --- content/en/configuration/markup.md | 68 ++-- content/en/configuration/output-formats.md | 90 +++-- .../en/content-management/content-adapters.md | 188 +++++----- content/en/content-management/mathematics.md | 169 +++++---- content/en/contribute/development.md | 126 +++---- content/en/contribute/documentation.md | 77 ++-- content/en/functions/css/PostCSS.md | 59 ++- content/en/functions/css/TailwindCSS.md | 123 +++---- content/en/functions/js/Babel.md | 29 +- content/en/functions/transform/ToMath.md | 93 +++-- .../host-on-aws-amplify/index.md | 230 ++++++------ .../host-on-cloudflare/index.md | 216 ++++++----- .../{gh-pages-1.png => gh-pages-01.png} | Bin .../{gh-pages-2.png => gh-pages-02.png} | Bin .../{gh-pages-3.png => gh-pages-03.png} | Bin .../{gh-pages-4.png => gh-pages-04.png} | Bin .../{gh-pages-5.png => gh-pages-05.png} | Bin .../host-on-github-pages/index.md | 341 ++++++++---------- .../host-and-deploy/host-on-netlify/index.md | 115 +++--- .../host-and-deploy/host-on-render/index.md | 225 ++++++------ .../host-and-deploy/host-on-vercel/index.md | 219 ++++++----- 21 files changed, 1108 insertions(+), 1260 deletions(-) rename content/en/host-and-deploy/host-on-github-pages/{gh-pages-1.png => gh-pages-01.png} (100%) rename content/en/host-and-deploy/host-on-github-pages/{gh-pages-2.png => gh-pages-02.png} (100%) rename content/en/host-and-deploy/host-on-github-pages/{gh-pages-3.png => gh-pages-03.png} (100%) rename content/en/host-and-deploy/host-on-github-pages/{gh-pages-4.png => gh-pages-04.png} (100%) rename content/en/host-and-deploy/host-on-github-pages/{gh-pages-5.png => gh-pages-05.png} (100%) diff --git a/content/en/configuration/markup.md b/content/en/configuration/markup.md index ee2996b9b..bf5aac374 100644 --- a/content/en/configuration/markup.md +++ b/content/en/configuration/markup.md @@ -246,49 +246,47 @@ workingFolderCurrent Follow the steps below to enable syntax highlighting. -#### Step 1 +Step 1 +: Set the `source-highlighter` attribute in your site configuration. For example: -Set the `source-highlighter` attribute in your site configuration. For example: + {{< code-toggle file=hugo >}} + [markup.asciidocExt.attributes] + source-highlighter = 'rouge' + {{< /code-toggle >}} -{{< code-toggle file=hugo >}} -[markup.asciidocExt.attributes] -source-highlighter = 'rouge' -{{< /code-toggle >}} +Step 2 +: Generate the highlighter CSS. For example: -#### Step 2 + ```text + rougify style monokai.sublime > assets/css/syntax.css + ``` -Generate the highlighter CSS. For example: +Step 3 +: In your base template add a link to the CSS file: -```text -rougify style monokai.sublime > assets/css/syntax.css -``` + ```go-html-template {file="layouts/baseof.html"} + + ... + {{ with resources.Get "css/syntax.css" }} + + {{ end }} + ... + + ``` -#### Step 3 +Step 4 +: Add the code to be highlighted to your markup: -In your base template add a link to the CSS file: + ```text + [#hello,ruby] + ---- + require 'sinatra' -```go-html-template {file="layouts/baseof.html"} - - ... - {{ with resources.Get "css/syntax.css" }} - - {{ end }} - ... - -``` - -Then add the code to be highlighted to your markup: - -```text -[#hello,ruby] ----- -require 'sinatra' - -get '/hi' do - "Hello World!" -end ----- -``` + get '/hi' do + "Hello World!" + end + ---- + ``` ### Troubleshooting diff --git a/content/en/configuration/output-formats.md b/content/en/configuration/output-formats.md index ef91e3ede..7e80d30fb 100644 --- a/content/en/configuration/output-formats.md +++ b/content/en/configuration/output-formats.md @@ -44,25 +44,25 @@ isHTML : (`bool`) Whether to classify the output format as HTML. Hugo uses this value to determine when to create alias redirects and when to inject the LiveReload script. Default is `false`. isPlainText -: (`bool`) Whether to parse templates for this output format with Go's [text/template] package instead of the [html/template] package. Default is `false`. +: (`bool`) Whether to parse templates for this output format with Go's [text/template][] package instead of the [html/template][] package. Default is `false`. mediaType -: (`string`) The [media type](g) of the published file. This must match one of the [configured media types]. +: (`string`) The [media type](g) of the published file. This must match one of the [configured media types][]. notAlternative -: (`bool`) Whether to exclude this output format from the values returned by the [`AlternativeOutputFormats`] method on a `Page` object. Default is `false`. +: (`bool`) Whether to exclude this output format from the values returned by the [`AlternativeOutputFormats`][] method on a `Page` object. Default is `false`. noUgly -: (`bool`) Whether to disable ugly URLs for this output format when [`uglyURLs`] are enabled in your site configuration. Default is `false`. +: (`bool`) Whether to disable ugly URLs for this output format when [`uglyURLs`][] are enabled in your site configuration. Default is `false`. path -: (`string`) The first segment of the publication path for this output format. This path segment is relative to the root of your [`publishDir`]. If omitted, Hugo will use the file's original content path for publishing. +: (`string`) The first segment of the publication path for this output format. This path segment is relative to the root of your [`publishDir`][]. If omitted, Hugo will use the file's original content path for publishing. permalinkable -: (`bool`) Whether to return the rendering output format rather than main output format when invoking the [`Permalink`] and [`RelPermalink`] methods on a `Page` object. See [details](#link-to-output-formats). Enabled by default for the `html` and `amp` output formats. Default is `false`. +: (`bool`) Whether to return the rendering output format rather than main output format when invoking the [`Permalink`][] and [`RelPermalink`][] methods on a `Page` object. See [details](#link-to-output-formats). Enabled by default for the `html` and `amp` output formats. Default is `false`. protocol -: (`string`) The protocol (scheme) of the URL for this output format. For example, `https://` or `webcal://`. Default is the scheme of the [`baseURL`] parameter in your site configuration, typically `https://`. +: (`string`) The protocol (scheme) of the URL for this output format. For example, `https://` or `webcal://`. Default is the scheme of the [`baseURL`][] parameter in your site configuration, typically `https://`. rel : (`string`) If provided, you can assign this value to `rel` attributes in `link` elements when iterating over output formats in your templates. Default is `alternate`. @@ -93,56 +93,52 @@ The example above shows that when you modify a default content format, you only You can create new output formats as needed. For example, you may wish to create an output format to support Atom feeds. -### Step 1 +Step 1 +: Output formats require a specified media type. Because Atom feeds use `application/atom+xml`, which is not one of the [default media types][], you must create it first. -Output formats require a specified media type. Because Atom feeds use `application/atom+xml`, which is not one of the [default media types], you must create it first. + {{< code-toggle file=hugo >}} + [mediaTypes.'application/atom+xml'] + suffixes = ['atom'] + {{< /code-toggle >}} -{{< code-toggle file=hugo >}} -[mediaTypes.'application/atom+xml'] -suffixes = ['atom'] -{{< /code-toggle >}} + See [configure media types][] for more information. -See [configure media types] for more information. +Step 2 +: Create a new output format: -### Step 2 + {{< code-toggle file=hugo >}} + [outputFormats.atom] + mediaType = 'application/atom+xml' + noUgly = true + {{< /code-toggle >}} -Create a new output format: + Note that we use the default settings for all other output format properties. -{{< code-toggle file=hugo >}} -[outputFormats.atom] -mediaType = 'application/atom+xml' -noUgly = true -{{< /code-toggle >}} +Step 3 +: Specify the page [kinds](g) for which to render this output format: -Note that we use the default settings for all other output format properties. + {{< code-toggle file=hugo >}} + [outputs] + home = ['html', 'rss', 'atom'] + section = ['html', 'rss', 'atom'] + taxonomy = ['html', 'rss', 'atom'] + term = ['html', 'rss', 'atom'] + {{< /code-toggle >}} -### Step 3 + See [configure outputs][] for more information. -Specify the page [kinds](g) for which to render this output format: +Step 4 +: Create a template to render the output format. Since Atom feeds are lists, you need to create a list template. Consult the [template lookup order] to find the correct template path: -{{< code-toggle file=hugo >}} -[outputs] -home = ['html', 'rss', 'atom'] -section = ['html', 'rss', 'atom'] -taxonomy = ['html', 'rss', 'atom'] -term = ['html', 'rss', 'atom'] -{{< /code-toggle >}} + ```text + layouts/list.atom.atom + ``` -See [configure outputs] for more information. - -### Step 4 - -Create a template to render the output format. Since Atom feeds are lists, you need to create a list template. Consult the [template lookup order] to find the correct template path: - -```text -layouts/list.atom.atom -``` - -We leave writing the template code as an exercise for you. Aim for a result similar to the [embedded RSS template]. + We leave writing the template code as an exercise for you. Aim for a result similar to the [embedded RSS template][]. ## List output formats -To access output formats, each `Page` object provides two methods: [`OutputFormats`] (for all formats, including the current one) and [`AlternativeOutputFormats`]. Use `AlternativeOutputFormats` to create a link `rel` list within your site's `head` element, as shown below: +To access output formats, each `Page` object provides two methods: [`OutputFormats`][] (for all formats, including the current one) and [`AlternativeOutputFormats`][]. Use `AlternativeOutputFormats` to create a link `rel` list within your site's `head` element, as shown below: ```go-html-template {{ range .AlternativeOutputFormats }} @@ -152,7 +148,7 @@ To access output formats, each `Page` object provides two methods: [`OutputForma ## Link to output formats -By default, a `Page` object's [`Permalink`] and [`RelPermalink`] methods return the URL of the [primary output format](g), typically `html`. This behavior remains consistent regardless of the template used. +By default, a `Page` object's [`Permalink`][] and [`RelPermalink`][] methods return the URL of the [primary output format](g), typically `html`. This behavior remains consistent regardless of the template used. For example, in `page.json.json`, you'll see: @@ -163,7 +159,7 @@ For example, in `page.json.json`, you'll see: {{ end }} ``` -To make these methods return the URL of the _current_ template's output format, you must set the [`permalinkable`] setting to `true` for that format. +To make these methods return the URL of the _current_ template's output format, you must set the [`permalinkable`][] setting to `true` for that format. With `permalinkable` set to true for `json` in the same `page.json.json` template: @@ -176,7 +172,7 @@ With `permalinkable` set to true for `json` in the same `page.json.json` templat ## Template lookup order -Each output format requires a template conforming to the [template lookup order]. +Each output format requires a template conforming to the [template lookup order][]. For the highest specificity in the template lookup order, include the page kind, output format, and suffix in the file name: @@ -204,7 +200,7 @@ Output format|Template path [configure outputs]: /configuration/outputs/ [configured media types]: /configuration/media-types/ [default media types]: /configuration/media-types/ -[embedded RSS template]: {{% eturl rss %}} +[embedded RSS template]: <{{% eturl rss %}}> [html/template]: https://pkg.go.dev/html/template [template lookup order]: /templates/lookup-order/ [text/template]: https://pkg.go.dev/text/template diff --git a/content/en/content-management/content-adapters.md b/content/en/content-management/content-adapters.md index e2f567ce8..9eae86266 100644 --- a/content/en/content-management/content-adapters.md +++ b/content/en/content-management/content-adapters.md @@ -161,113 +161,109 @@ Key|Description|Required Create pages from remote data, where each page represents a book review. -### Step 1 +Step 1 +: Create the content structure. -Create the content structure. + ```text + content/ + └── books/ + ├── _content.gotmpl <-- content adapter + └── _index.md + ``` -```text -content/ -└── books/ - ├── _content.gotmpl <-- content adapter - └── _index.md -``` +Step 2 +: Inspect the remote data to determine how to map key-value pairs to front matter fields.\ + -### Step 2 +Step 3 +: Create the content adapter. -Inspect the remote data to determine how to map key-value pairs to front matter fields.\ - - -### Step 3 - -Create the content adapter. - -```go-html-template {file="content/books/_content.gotmpl" copy=true} -{{/* Get remote data. */}} -{{ $data := dict }} -{{ $url := "https://gohugo.io/shared/examples/data/books.json" }} -{{ with try (resources.GetRemote $url) }} - {{ with .Err }} - {{ errorf "Unable to get remote resource %s: %s" $url . }} - {{ else with .Value }} - {{ $data = . | transform.Unmarshal }} - {{ else }} - {{ errorf "Unable to get remote resource %s" $url }} - {{ end }} -{{ end }} - -{{/* Add pages and page resources. */}} -{{ range $data }} - - {{/* Add page. */}} - {{ $content := dict "mediaType" "text/markdown" "value" .summary }} - {{ $dates := dict "date" (time.AsTime .date) }} - {{ $params := dict "author" .author "isbn" .isbn "rating" .rating "tags" .tags }} - {{ $page := dict - "content" $content - "dates" $dates - "kind" "page" - "params" $params - "path" .title - "title" .title - }} - {{ $.AddPage $page }} - - {{/* Add page resource. */}} - {{ $item := . }} - {{ with $url := $item.cover }} - {{ with try (resources.GetRemote $url) }} - {{ with .Err }} - {{ errorf "Unable to get remote resource %s: %s" $url . }} - {{ else with .Value }} - {{ $content := dict "mediaType" .MediaType.Type "value" .Content }} - {{ $params := dict "alt" $item.title }} - {{ $resource := dict - "content" $content - "params" $params - "path" (printf "%s/cover.%s" $item.title .MediaType.SubType) - }} - {{ $.AddResource $resource }} - {{ else }} - {{ errorf "Unable to get remote resource %s" $url }} - {{ end }} + ```go-html-template {file="content/books/_content.gotmpl" copy=true} + {{/* Get remote data. */}} + {{ $data := dict }} + {{ $url := "https://gohugo.io/shared/examples/data/books.json" }} + {{ with try (resources.GetRemote $url) }} + {{ with .Err }} + {{ errorf "Unable to get remote resource %s: %s" $url . }} + {{ else with .Value }} + {{ $data = . | transform.Unmarshal }} + {{ else }} + {{ errorf "Unable to get remote resource %s" $url }} {{ end }} {{ end }} -{{ end }} -``` + {{/* Add pages and page resources. */}} + {{ range $data }} -### Step 4 + {{/* Add page. */}} + {{ $content := dict "mediaType" "text/markdown" "value" .summary }} + {{ $dates := dict "date" (time.AsTime .date) }} + {{ $params := dict "author" .author "isbn" .isbn "rating" .rating "tags" .tags }} + {{ $page := dict + "content" $content + "dates" $dates + "kind" "page" + "params" $params + "path" .title + "title" .title + }} + {{ $.AddPage $page }} -Create a _page_ template to render each book review. - -```go-html-template {file="layouts/books/page.html" copy=true} -{{ define "main" }} -

{{ .Title }}

- - {{ with .Resources.GetMatch "cover.*" }} - {{ .Params.alt }} - {{ end }} - -

Author: {{ .Params.author }}

- -

- ISBN: {{ .Params.isbn }}
- Rating: {{ .Params.rating }}
- Review date: {{ .Date | time.Format ":date_long" }} -

- - {{ with .GetTerms "tags" }} -

Tags:

-
    - {{ range . }} -
  • {{ .LinkTitle }}
    • + {{/* Add page resource. */}} + {{ $item := . }} + {{ with $url := $item.cover }} + {{ with try (resources.GetRemote $url) }} + {{ with .Err }} + {{ errorf "Unable to get remote resource %s: %s" $url . }} + {{ else with .Value }} + {{ $content := dict "mediaType" .MediaType.Type "value" .Content }} + {{ $params := dict "alt" $item.title }} + {{ $resource := dict + "content" $content + "params" $params + "path" (printf "%s/cover.%s" $item.title .MediaType.SubType) + }} + {{ $.AddResource $resource }} + {{ else }} + {{ errorf "Unable to get remote resource %s" $url }} + {{ end }} {{ end }} -
- {{ end }} + {{ end }} - {{ .Content }} -{{ end }} -``` + {{ end }} + ``` + +Step 4 +: Create a _page_ template to render each book review. + + ```go-html-template {file="layouts/books/page.html" copy=true} + {{ define "main" }} +

{{ .Title }}

+ + {{ with .Resources.GetMatch "cover.*" }} + {{ .Params.alt }} + {{ end }} + +

Author: {{ .Params.author }}

+ +

+ ISBN: {{ .Params.isbn }}
+ Rating: {{ .Params.rating }}
+ Review date: {{ .Date | time.Format ":date_long" }} +

+ + {{ with .GetTerms "tags" }} +

Tags:

+ + {{ end }} + + {{ .Content }} + {{ end }} + ``` ## Multilingual sites diff --git a/content/en/content-management/mathematics.md b/content/en/content-management/mathematics.md index 0dbe4ef25..aaa8c2394 100644 --- a/content/en/content-management/mathematics.md +++ b/content/en/content-management/mathematics.md @@ -45,117 +45,114 @@ Whether an equation or expression appears inline, or as a block, depends on the Follow these instructions to include mathematical equations and expressions in your Markdown using LaTeX markup. -### Step 1 +Step 1 +: Enable and configure the Goldmark [passthrough extension] in your site configuration. The passthrough extension preserves raw Markdown within delimited snippets of text, including the delimiters themselves. -Enable and configure the Goldmark [passthrough extension] in your site configuration. The passthrough extension preserves raw Markdown within delimited snippets of text, including the delimiters themselves. + {{< code-toggle file=hugo copy=true >}} + [markup.goldmark.extensions.passthrough] + enable = true -{{< code-toggle file=hugo copy=true >}} -[markup.goldmark.extensions.passthrough] -enable = true + [markup.goldmark.extensions.passthrough.delimiters] + block = [['\[', '\]'], ['$$', '$$']] + inline = [['\(', '\)']] -[markup.goldmark.extensions.passthrough.delimiters] -block = [['\[', '\]'], ['$$', '$$']] -inline = [['\(', '\)']] + [params] + math = true + {{< /code-toggle >}} -[params] -math = true -{{< /code-toggle >}} + The configuration above enables mathematical rendering on every page unless you set the `math` parameter to `false` in front matter. To enable mathematical rendering as needed, set the `math` parameter to `false` in your site configuration, and set the `math` parameter to `true` in front matter. Use this parameter in your base template as shown in [Step 3](#step-3). -The configuration above enables mathematical rendering on every page unless you set the `math` parameter to `false` in front matter. To enable mathematical rendering as needed, set the `math` parameter to `false` in your site configuration, and set the `math` parameter to `true` in front matter. Use this parameter in your base template as shown in [Step 3]. + > [!note] + > The configuration above precludes the use of the `$...$` delimiter pair for inline equations. Although you can add this delimiter pair to the configuration and JavaScript, you must double-escape the `$` symbol when used outside of math contexts to avoid unintended formatting. + > + > See the [inline delimiters](#inline-delimiters) section for details. -> [!note] -> The configuration above precludes the use of the `$...$` delimiter pair for inline equations. Although you can add this delimiter pair to the configuration and JavaScript, you must double-escape the `$` symbol when used outside of math contexts to avoid unintended formatting. -> -> See the [inline delimiters](#inline-delimiters) section for details. + To disable passthrough of inline snippets, omit the `inline` key from the configuration: -To disable passthrough of inline snippets, omit the `inline` key from the configuration: + {{< code-toggle file=hugo >}} + [markup.goldmark.extensions.passthrough.delimiters] + block = [['\[', '\]'], ['$$', '$$']] + {{< /code-toggle >}} -{{< code-toggle file=hugo >}} -[markup.goldmark.extensions.passthrough.delimiters] -block = [['\[', '\]'], ['$$', '$$']] -{{< /code-toggle >}} + You can define your own opening and closing delimiters, provided they match the delimiters that you set in [Step 2]. -You can define your own opening and closing delimiters, provided they match the delimiters that you set in [Step 2]. + {{< code-toggle file=hugo >}} + [markup.goldmark.extensions.passthrough.delimiters] + block = [['@@', '@@']] + inline = [['@', '@']] + {{< /code-toggle >}} -{{< code-toggle file=hugo >}} -[markup.goldmark.extensions.passthrough.delimiters] -block = [['@@', '@@']] -inline = [['@', '@']] -{{< /code-toggle >}} +Step 2 +: Create a _partial_ template to load MathJax or KaTeX. The example below loads MathJax, or you can use KaTeX as described in the [engines](#engines) section. -### Step 2 + ```go-html-template {file="layouts/_partials/math.html" copy=true} + + + ``` -Create a _partial_ template to load MathJax or KaTeX. The example below loads MathJax, or you can use KaTeX as described in the [engines](#engines) section. + The delimiters above must match the delimiters in your site configuration. -```go-html-template {file="layouts/_partials/math.html" copy=true} - - -``` +Step 3 +: Conditionally call the _partial_ template from the base template. -The delimiters above must match the delimiters in your site configuration. + ```go-html-template {file="layouts/baseof.html"} + + ... + {{ if .Param "math" }} + {{ partialCached "math.html" . }} + {{ end }} + ... + + ``` -### Step 3 + The example above loads the _partial_ template if you have set the `math` parameter in front matter to `true`. If you have not set the `math` parameter in front matter, the conditional statement falls back to the `math` parameter in your site configuration. -Conditionally call the _partial_ template from the base template. +Step 4 +: If you set the `math` parameter to `false` in your site configuration, you must set the `math` parameter to `true` in front matter. For example: -```go-html-template {file="layouts/baseof.html"} - - ... - {{ if .Param "math" }} - {{ partialCached "math.html" . }} - {{ end }} - ... - -``` + {{< code-toggle file=content/math-examples.md fm=true >}} + title = 'Math examples' + date = 2024-01-24T18:09:49-08:00 + [params] + math = true + {{< /code-toggle >}} -The example above loads the _partial_ template if you have set the `math` parameter in front matter to `true`. If you have not set the `math` parameter in front matter, the conditional statement falls back to the `math` parameter in your site configuration. +Step 5 +: Include mathematical equations and expressions in Markdown using LaTeX markup. -### Step 4 + ```text {file="content/math-examples.md" copy=true} + This is an inline \(a^*=x-b^*\) equation. -Include mathematical equations and expressions in Markdown using LaTeX markup. + These are block equations: -```text {file="content/math-examples.md" copy=true} -This is an inline \(a^*=x-b^*\) equation. + \[a^*=x-b^*\] -These are block equations: + \[ a^*=x-b^* \] -\[a^*=x-b^*\] + \[ + a^*=x-b^* + \] -\[ a^*=x-b^* \] + These are also block equations: -\[ -a^*=x-b^* -\] + $$a^*=x-b^*$$ -These are also block equations: + $$ a^*=x-b^* $$ -$$a^*=x-b^*$$ - -$$ a^*=x-b^* $$ - -$$ -a^*=x-b^* -$$ -``` - -If you set the `math` parameter to `false` in your site configuration, you must set the `math` parameter to `true` in front matter. For example: - -{{< code-toggle file=content/math-examples.md fm=true >}} -title = 'Math examples' -date = 2024-01-24T18:09:49-08:00 -[params] -math = true -{{< /code-toggle >}} + $$ + a^*=x-b^* + $$ + ``` ## Inline delimiters @@ -227,12 +224,10 @@ $$C_p[\ce{H2O(l)}] = \pu{75.3 J // mol K}$$ $$C_p[\ce{H2O(l)}] = \pu{75.3 J // mol K}$$ -As shown in [Step 2] above, MathJax supports chemical equations without additional configuration. To add chemistry support to KaTeX, enable the mhchem extension as described in the KaTeX [documentation](https://katex.org/docs/libs). +As shown in [Step 2](#step-2) above, MathJax supports chemical equations without additional configuration. To add chemistry support to KaTeX, enable the mhchem extension as described in the KaTeX [documentation](https://katex.org/docs/libs). [`transform.ToMath`]: /functions/transform/tomath/ [KaTeX]: https://katex.org/ [LaTeX]: https://www.latex-project.org/ [MathJax]: https://www.mathjax.org/ [passthrough extension]: /configuration/markup/#passthrough -[Step 2]: #step-2 -[Step 3]: #step-3 diff --git a/content/en/contribute/development.md b/content/en/contribute/development.md index fdbe4e4c2..5930fbf52 100644 --- a/content/en/contribute/development.md +++ b/content/en/contribute/development.md @@ -46,99 +46,89 @@ To build the extended or extended/deploy edition from source you must: Use this workflow to create and submit pull requests. -### Step 1 +Step 1 +: Fork the [project repository]. -Fork the [project repository]. +Step 2 +: Clone your fork. -### Step 2 +Step 3 +: Create a new branch with a descriptive name that includes the corresponding issue number. -Clone your fork. + For a new feature: -### Step 3 + ```sh + git checkout -b feat/implement-some-feature-99999 + ``` -Create a new branch with a descriptive name that includes the corresponding issue number. + For a bug fix: -For a new feature: + ```sh + git checkout -b fix/fix-some-bug-99999 + ``` -```sh -git checkout -b feat/implement-some-feature-99999 -``` +Step 4 +: Make changes. -For a bug fix: +Step 5 +: Compile and install. -```sh -git checkout -b fix/fix-some-bug-99999 -``` + To compile and install the standard edition: -### Step 4 + ```text + go install + ``` -Make changes. + To compile and install the extended edition: -### Step 5 + ```text + CGO_ENABLED=1 go install -tags extended + ``` -Compile and install. + To compile and install the extended/deploy edition: -To compile and install the standard edition: + ```text + CGO_ENABLED=1 go install -tags extended,withdeploy + ``` -```text -go install -``` +Step 6 +: Test your changes: -To compile and install the extended edition: + ```text + go test ./... + ``` -```text -CGO_ENABLED=1 go install -tags extended -``` +Step 7 +: Commit your changes with a descriptive commit message: -To compile and install the extended/deploy edition: + - Provide a summary on the first line, typically 50 characters or less, followed by a blank line. + - Begin the summary with one of content, theme, config, all, or misc, followed by a colon, a space, and a brief description of the change beginning with a capital letter + - Use imperative present tense + - See the [commit message guidelines] for requirements + - Optionally, provide a detailed description where each line is 72 characters or less, followed by a blank line. + - Add one or more "Fixes" or "Closes" keywords, each on its own line, referencing the [issues] addressed by this change. -```text -CGO_ENABLED=1 go install -tags extended,withdeploy -``` + For example: -### Step 6 + ```sh + git commit -m "tpl/strings: Create wrap function -Test your changes: + The strings.Wrap function wraps a string into one or more lines, + splitting the string after the given number of characters, but not + splitting in the middle of a word. -```text -go test ./... -``` + Fixes #99998 + Closes #99999" + ``` -### Step 7 +Step 8 +: Push the new branch to your fork of the documentation repository. -Commit your changes with a descriptive commit message: +Step 9 +: Visit the [project repository] and create a pull request (PR). -- Provide a summary on the first line, typically 50 characters or less, followed by a blank line. - - Begin the summary with one of content, theme, config, all, or misc, followed by a colon, a space, and a brief description of the change beginning with a capital letter - - Use imperative present tense - - See the [commit message guidelines] for requirements -- Optionally, provide a detailed description where each line is 72 characters or less, followed by a blank line. -- Add one or more "Fixes" or "Closes" keywords, each on its own line, referencing the [issues] addressed by this change. - -For example: - -```sh -git commit -m "tpl/strings: Create wrap function - -The strings.Wrap function wraps a string into one or more lines, -splitting the string after the given number of characters, but not -splitting in the middle of a word. - -Fixes #99998 -Closes #99999" -``` - -### Step 8 - -Push the new branch to your fork of the documentation repository. - -### Step 9 - -Visit the [project repository] and create a pull request (PR). - -### Step 10 - -A project maintainer will review your PR and may request changes. You may delete your branch after the maintainer merges your PR. +Step 10 +: A project maintainer will review your PR and may request changes. You may delete your branch after the maintainer merges your PR. ## Building from source diff --git a/content/en/contribute/documentation.md b/content/en/contribute/documentation.md index 289e59cdd..2ce2db169 100644 --- a/content/en/contribute/documentation.md +++ b/content/en/contribute/documentation.md @@ -471,63 +471,54 @@ Set the `expiryDate` to two years from the date of deprecation, and add a brief Use this workflow to create and submit pull requests. -### Step 1 +Step 1 +: Fork the [documentation repository]. -Fork the [documentation repository]. +Step 2 +: Clone your fork. -### Step 2 +Step 3 +: Create a new branch with a descriptive name that includes the corresponding issue number, if any: -Clone your fork. + ```sh + git checkout -b restructure-foo-page-99999 + ``` -### Step 3 +Step 4 +: Make changes. -Create a new branch with a descriptive name that includes the corresponding issue number, if any: +Step 5 +: Build the site locally to preview your changes. -```sh -git checkout -b restructure-foo-page-99999 -``` +Step 6 +: Commit your changes with a descriptive commit message: -### Step 4 + - Provide a summary on the first line, typically 50 characters or less, followed by a blank line. + - Begin the summary with one of `content`, `theme`, `config`, `all`, or `misc`, followed by a colon, a space, and a brief description of the change beginning with a capital letter + - Use imperative present tense + - Optionally, provide a detailed description where each line is 72 characters or less, followed by a blank line. + - Optionally, add one or more "Fixes" or "Closes" keywords, each on its own line, referencing the [issues] addressed by this change. -Make changes. + For example: -### Step 5 + ```text + git commit -m "content: Restructure the taxonomy page -Build the site locally to preview your changes. + This restructures the taxonomy page by splitting topics into logical + sections, each with one or more examples. -### Step 6 + Fixes #9999 + Closes #9998" + ``` -Commit your changes with a descriptive commit message: +Step 7 +: Push the new branch to your fork of the documentation repository. -- Provide a summary on the first line, typically 50 characters or less, followed by a blank line. - - Begin the summary with one of `content`, `theme`, `config`, `all`, or `misc`, followed by a colon, a space, and a brief description of the change beginning with a capital letter - - Use imperative present tense -- Optionally, provide a detailed description where each line is 72 characters or less, followed by a blank line. -- Optionally, add one or more "Fixes" or "Closes" keywords, each on its own line, referencing the [issues] addressed by this change. +Step 8 +: Visit the [documentation repository] and create a pull request (PR). -For example: - -```text -git commit -m "content: Restructure the taxonomy page - -This restructures the taxonomy page by splitting topics into logical -sections, each with one or more examples. - -Fixes #9999 -Closes #9998" -``` - -### Step 7 - -Push the new branch to your fork of the documentation repository. - -### Step 8 - -Visit the [documentation repository] and create a pull request (PR). - -### Step 9 - -A project maintainer will review your PR and may request changes. You may delete your branch after the maintainer merges your PR. +Step 9 +: A project maintainer will review your PR and may request changes. You may delete your branch after the maintainer merges your PR. [ATX]: https://spec.commonmark.org/current/#atx-headings [basic english]: https://simple.wikipedia.org/wiki/Basic_English diff --git a/content/en/functions/css/PostCSS.md b/content/en/functions/css/PostCSS.md index 9cc698248..4dce705be 100644 --- a/content/en/functions/css/PostCSS.md +++ b/content/en/functions/css/PostCSS.md @@ -22,46 +22,41 @@ params: Follow the steps below to transform CSS using any of the available [PostCSS plugins]. -### Step 1 +Step 1 +: Install [Node.js]. -Install [Node.js]. +Step 2 +: Install the required Node.js packages in the root of your project. For example, to add vendor prefixes to your CSS rules: -### Step 2 + ```sh + npm i -D postcss postcss-cli autoprefixer + ``` -Install the required Node.js packages in the root of your project. For example, to add vendor prefixes to your CSS rules: +Step 3 +: Create a PostCSS configuration file in the root of your project. -```sh -npm i -D postcss postcss-cli autoprefixer -``` + ```js {file="postcss.config.js"} + module.exports = { + plugins: [ + require('autoprefixer') + ] + }; + ``` -### Step 3 + > [!note] + > If you are a Windows user, and the path to your project contains a space, you must place the PostCSS configuration within the package.json file. See [this example] and issue [#7333]. -Create a PostCSS configuration file in the root of your project. +Step 4 +: Place your CSS file within the `assets/css` directory. -```js {file="postcss.config.js"} -module.exports = { - plugins: [ - require('autoprefixer') - ] -}; -``` +Step 5 +: Process the resource with PostCSS: -> [!note] -> If you are a Windows user, and the path to your project contains a space, you must place the PostCSS configuration within the package.json file. See [this example] and issue [#7333]. - -### Step 4 - -Place your CSS file within the `assets/css` directory. - -### Step 5 - -Process the resource with PostCSS: - -```go-html-template -{{ with resources.Get "css/main.css" | postCSS }} - -{{ end }} -``` + ```go-html-template + {{ with resources.Get "css/main.css" | postCSS }} + + {{ end }} + ``` ## Options diff --git a/content/en/functions/css/TailwindCSS.md b/content/en/functions/css/TailwindCSS.md index f9ac90316..e8514679b 100644 --- a/content/en/functions/css/TailwindCSS.md +++ b/content/en/functions/css/TailwindCSS.md @@ -25,85 +25,80 @@ Use the `css.TailwindCSS` function to process your Tailwind CSS files. This func ## Setup -### Step 1 +Step 1 +: Install the Tailwind CSS CLI v4.0 or later: -Install the Tailwind CSS CLI v4.0 or later: + ```sh {copy=true} + npm install --save-dev tailwindcss @tailwindcss/cli + ``` -```sh {copy=true} -npm install --save-dev tailwindcss @tailwindcss/cli -``` + The Tailwind CSS CLI is also available as a [standalone executable]. You must install it outside of your project directory and ensure its path is included in your system's `PATH` environment variable. -The Tailwind CSS CLI is also available as a [standalone executable]. You must install it outside of your project directory and ensure its path is included in your system's `PATH` environment variable. + [standalone executable]: https://github.com/tailwindlabs/tailwindcss/releases/latest -[standalone executable]: https://github.com/tailwindlabs/tailwindcss/releases/latest +Step 2 +: Add this to your site configuration: -### Step 2 + {{< code-toggle file=hugo copy=true >}} + [build] + [build.buildStats] + enable = true + [[build.cachebusters]] + source = 'assets/notwatching/hugo_stats\.json' + target = 'css' + [[build.cachebusters]] + source = '(postcss|tailwind)\.config\.js' + target = 'css' + [module] + [[module.mounts]] + source = 'assets' + target = 'assets' + [[module.mounts]] + disableWatch = true + source = 'hugo_stats.json' + target = 'assets/notwatching/hugo_stats.json' + {{< /code-toggle >}} -Add this to your site configuration: +Step 3 +: Create a CSS entry file: -{{< code-toggle file=hugo copy=true >}} -[build] - [build.buildStats] - enable = true - [[build.cachebusters]] - source = 'assets/notwatching/hugo_stats\.json' - target = 'css' - [[build.cachebusters]] - source = '(postcss|tailwind)\.config\.js' - target = 'css' -[module] - [[module.mounts]] - source = 'assets' - target = 'assets' - [[module.mounts]] - disableWatch = true - source = 'hugo_stats.json' - target = 'assets/notwatching/hugo_stats.json' -{{< /code-toggle >}} + ```css {file="assets/css/main.css" copy=true} + @import "tailwindcss"; + @source "hugo_stats.json"; + ``` -### Step 3 + Tailwind CSS respects `.gitignore` files. This means that if `hugo_stats.json` is listed in your `.gitignore` file, Tailwind CSS will ignore it. To make `hugo_stats.json` available to Tailwind CSS you must explicitly source it as shown in the example above. -Create a CSS entry file: +Step 4 +: Create a _partial_ template to process the CSS with the Tailwind CSS CLI: -```css {file="assets/css/main.css" copy=true} -@import "tailwindcss"; -@source "hugo_stats.json"; -``` - -Tailwind CSS respects `.gitignore` files. This means that if `hugo_stats.json` is listed in your `.gitignore` file, Tailwind CSS will ignore it. To make `hugo_stats.json` available to Tailwind CSS you must explicitly source it as shown in the example above. - -### Step 4 - -Create a _partial_ template to process the CSS with the Tailwind CSS CLI: - -```go-html-template {file="layouts/_partials/css.html" copy=true} -{{ with resources.Get "css/main.css" }} - {{ $opts := dict "minify" (not hugo.IsDevelopment) }} - {{ with . | css.TailwindCSS $opts }} - {{ if hugo.IsDevelopment }} - - {{ else }} - {{ with . | fingerprint }} - + ```go-html-template {file="layouts/_partials/css.html" copy=true} + {{ with resources.Get "css/main.css" }} + {{ $opts := dict "minify" (not hugo.IsDevelopment) }} + {{ with . | css.TailwindCSS $opts }} + {{ if hugo.IsDevelopment }} + + {{ else }} + {{ with . | fingerprint }} + + {{ end }} {{ end }} {{ end }} {{ end }} -{{ end }} -``` + ``` -### Step 5 +Step 5 +: Call the _partial_ template from your base template, deferring template execution until after all sites and output formats have been rendered: -Call the _partial_ template from your base template, deferring template execution until after all sites and output formats have been rendered: - -```go-html-template {file="layouts/baseof.html" copy=true} - - ... - {{ with (templates.Defer (dict "key" "global")) }} - {{ partial "css.html" . }} - {{ end }} - ... - -``` + ```go-html-template {file="layouts/baseof.html" copy=true} + + ... + {{ with (templates.Defer (dict "key" "global")) }} + {{ partial "css.html" . }} + {{ end }} + ... + + ``` ## Options diff --git a/content/en/functions/js/Babel.md b/content/en/functions/js/Babel.md index d0007aaa0..488c80503 100644 --- a/content/en/functions/js/Babel.md +++ b/content/en/functions/js/Babel.md @@ -31,26 +31,23 @@ params: ## Setup -### Step 1 +Step 1 +: Install [Node.js](https://nodejs.org/en/download) -Install [Node.js](https://nodejs.org/en/download) +Step 2 +: Install the required Node.js packages in the root of your project. -### Step 2 + ```sh + npm install --save-dev @babel/core @babel/cli + ``` -Install the required Node.js packages in the root of your project. +Step 3 +: Add the babel executable to Hugo's `security.exec.allow` list in your site configuration: -```sh -npm install --save-dev @babel/core @babel/cli -``` - -### Step 3 - -Add the babel executable to Hugo's `security.exec.allow` list in your site configuration: - -{{< code-toggle file=hugo >}} -[security.exec] - allow = ['^(dart-)?sass(-embedded)?$', '^go$', '^npx$', '^postcss$', '^babel$'] -{{< /code-toggle >}} + {{< code-toggle file=hugo >}} + [security.exec] + allow = ['^(dart-)?sass(-embedded)?$', '^go$', '^npx$', '^postcss$', '^babel$'] + {{< /code-toggle >}} ## Configuration diff --git a/content/en/functions/transform/ToMath.md b/content/en/functions/transform/ToMath.md index 3a54e65d3..be62e8bce 100644 --- a/content/en/functions/transform/ToMath.md +++ b/content/en/functions/transform/ToMath.md @@ -92,70 +92,65 @@ The example below demonstrates error handing within a template. Instead of client-side JavaScript rendering of mathematical markup using MathJax or KaTeX, create a passthrough render hook which calls the `transform.ToMath` function. -### Step 1 - -Enable and configure the Goldmark [passthrough extension] in your site configuration. The passthrough extension preserves raw Markdown within delimited snippets of text, including the delimiters themselves. +Step 1 +: Enable and configure the Goldmark [passthrough extension][] in your site configuration. The passthrough extension preserves raw Markdown within delimited snippets of text, including the delimiters themselves. [passthrough extension]: /configuration/markup/#passthrough -{{< code-toggle file=hugo copy=true >}} -[markup.goldmark.extensions.passthrough] -enable = true + {{< code-toggle file=hugo copy=true >}} + [markup.goldmark.extensions.passthrough] + enable = true + [markup.goldmark.extensions.passthrough.delimiters] + block = [['\[', '\]'], ['$$', '$$']] + inline = [['\(', '\)']] + {{< /code-toggle >}} -[markup.goldmark.extensions.passthrough.delimiters] -block = [['\[', '\]'], ['$$', '$$']] -inline = [['\(', '\)']] -{{< /code-toggle >}} + > [!note] + > The configuration above precludes the use of the `$...$` delimiter pair for inline equations. Although you can add this delimiter pair to the configuration, you must double-escape the `$` symbol when used outside of math contexts to avoid unintended formatting. -> [!note] -> The configuration above precludes the use of the `$...$` delimiter pair for inline equations. Although you can add this delimiter pair to the configuration, you must double-escape the `$` symbol when used outside of math contexts to avoid unintended formatting. - -### Step 2 - -Create a [passthrough render hook] to capture and render the LaTeX markup. +Step 2 +: Create a [passthrough render hook][] to capture and render the LaTeX markup.4 [passthrough render hook]: /render-hooks/passthrough/ -```go-html-template {file="layouts/_markup/render-passthrough.html" copy=true} -{{- $opts := dict "output" "htmlAndMathml" "displayMode" (eq .Type "block") }} -{{- with try (transform.ToMath .Inner $opts) }} - {{- with .Err }} - {{- errorf "Unable to render mathematical markup to HTML using the transform.ToMath function. The KaTeX display engine threw the following error: %s: see %s." . $.Position }} - {{- else }} - {{- .Value }} - {{- $.Page.Store.Set "hasMath" true }} - {{- end }} -{{- end -}} -``` + ```go-html-template {file="layouts/_markup/render-passthrough.html" copy=true} + {{- $opts := dict "output" "htmlAndMathml" "displayMode" (eq .Type "block") }} + {{- with try (transform.ToMath .Inner $opts) }} + {{- with .Err }} + {{- errorf "Unable to render mathematical markup to HTML using the transform.ToMath function. The KaTeX display engine threw the following error: %s: see %s." . $.Position }} + {{- else }} + {{- .Value }} + {{- $.Page.Store.Set "hasMath" true }} + {{- end }} + {{- end -}} + ``` + +Step 3 +: In your base template, conditionally include the KaTeX CSS within the head element. -### Step 3 + ```go-html-template {file="layouts/baseof.html" copy=true} + + {{ $noop := .WordCount }} + {{ if .Page.Store.Get "hasMath" }} + + {{ end }} + + ``` -In your base template, conditionally include the KaTeX CSS within the head element. + In the above, note the use of a [noop](g) statement to force content rendering before we check the value of `hasMath` with the `Store.Get` method. -```go-html-template {file="layouts/baseof.html" copy=true} - - {{ $noop := .WordCount }} - {{ if .Page.Store.Get "hasMath" }} - - {{ end }} - -``` +Step 4 +: Add some mathematical markup to your content, then test. -In the above, note the use of a [noop](g) statement to force content rendering before we check the value of `hasMath` with the `Store.Get` method. + ```text {file="content/example.md"} + This is an inline \(a^*=x-b^*\) equation. -### Step 4 + These are block equations: -Add some mathematical markup to your content, then test. + \[a^*=x-b^*\] -```text {file="content/example.md"} -This is an inline \(a^*=x-b^*\) equation. - -These are block equations: - -\[a^*=x-b^*\] - -$$a^*=x-b^*$$ -``` + $$a^*=x-b^*$$ + ``` ## Chemistry diff --git a/content/en/host-and-deploy/host-on-aws-amplify/index.md b/content/en/host-and-deploy/host-on-aws-amplify/index.md index a6d3b7419..4fd71f3f9 100644 --- a/content/en/host-and-deploy/host-on-aws-amplify/index.md +++ b/content/en/host-and-deploy/host-on-aws-amplify/index.md @@ -6,166 +6,152 @@ keywords: [] aliases: [/hosting-and-deployment/hosting-on-aws-amplify/] --- +Use these instructions to enable continuous deployment from a GitHub repository. The same general steps apply if you are using GitLab for version control. + ## Prerequisites Please complete the following tasks before continuing: -1. [Create an AWS account] -1. [Install Git] -1. [Create a Hugo site] and test it locally with `hugo server` -1. Commit the changes to your local repository -1. Push the local repository to your [GitHub], [GitLab], or [Bitbucket] account - -[Bitbucket]: https://bitbucket.org/product -[Create a Hugo site]: /getting-started/quick-start/ -[Create an AWS account]: https://aws.amazon.com/resources/create-account/ -[GitHub]: https://github.com -[GitLab]: https://about.gitlab.com/ -[Install Git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git +1. [Create](https://aws.amazon.com/resources/create-account/) an AWS account +1. [Log in](https://console.aws.amazon.com/) to your AWS account +1. [Create](https://github.com/signup) a GitHub account +1. [Log in](https://github.com/login) to your GitHub account +1. [Create](https://github.com/new) a GitHub repository for your project +1. [Create](https://git-scm.com/docs/git-init) a local Git repository for your project with a [remote](https://git-scm.com/docs/git-remote) reference to your GitHub repository +1. Create a Hugo site within your local Git repository and test it with the `hugo server` command +1. Commit the changes to your local Git repository and push to your GitHub repository. ## Procedure This procedure will enable continuous deployment from a GitHub repository. The procedure is essentially the same if you are using GitLab or Bitbucket. -### Step 1 +Step 1 +: Create a file named `amplify.yml` in the root of your project. -Create a file named `amplify.yml` in the root of your project. + ```sh + touch amplify.yml + ``` -```sh -touch amplify.yml -``` +Step 2 +: Copy and paste the YAML below into the file you created. Change the application versions and time zone as needed. -### Step 2 + ```yaml {file="amplify.yml" copy=true} + version: 1 + env: + variables: + # Application versions + DART_SASS_VERSION: 1.90.0 + GO_VERSION: 1.24.5 + HUGO_VERSION: 0.148.2 + # Time zone + TZ: Europe/Oslo + # Cache + HUGO_CACHEDIR: ${PWD}/.hugo + NPM_CONFIG_CACHE: ${PWD}/.npm + frontend: + phases: + preBuild: + commands: + # Create directory for user-specific executable files + - echo "Creating directory for user-specific executable files..." + - mkdir -p "${HOME}/.local" -Copy and paste the YAML below into the file you created. Change the application versions and time zone as needed. + # Install Dart Sass + - echo "Installing Dart Sass ${DART_SASS_VERSION}..." + - curl -sLJO "https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz" + - tar -C "${HOME}/.local" -xf "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz" + - rm "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz" + - export PATH="${HOME}/.local/dart-sass:${PATH}" -```yaml {file="amplify.yml" copy=true} -version: 1 -env: - variables: - # Application versions - DART_SASS_VERSION: 1.90.0 - GO_VERSION: 1.24.5 - HUGO_VERSION: 0.148.2 - # Time zone - TZ: Europe/Oslo - # Cache - HUGO_CACHEDIR: ${PWD}/.hugo - NPM_CONFIG_CACHE: ${PWD}/.npm -frontend: - phases: - preBuild: - commands: - # Create directory for user-specific executable files - - echo "Creating directory for user-specific executable files..." - - mkdir -p "${HOME}/.local" + # Install Go + - echo "Installing Go ${GO_VERSION}..." + - curl -sLJO "https://go.dev/dl/go${GO_VERSION}.linux-amd64.tar.gz" + - tar -C "${HOME}/.local" -xf "go${GO_VERSION}.linux-amd64.tar.gz" + - rm "go${GO_VERSION}.linux-amd64.tar.gz" + - export PATH="${HOME}/.local/go/bin:${PATH}" - # Install Dart Sass - - echo "Installing Dart Sass ${DART_SASS_VERSION}..." - - curl -sLJO "https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz" - - tar -C "${HOME}/.local" -xf "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz" - - rm "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz" - - export PATH="${HOME}/.local/dart-sass:${PATH}" + # Install Hugo + - echo "Installing Hugo ${HUGO_VERSION}..." + - curl -sLJO "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz" + - mkdir "${HOME}/.local/hugo" + - tar -C "${HOME}/.local/hugo" -xf "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz" + - rm "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz" + - export PATH="${HOME}/.local/hugo:${PATH}" - # Install Go - - echo "Installing Go ${GO_VERSION}..." - - curl -sLJO "https://go.dev/dl/go${GO_VERSION}.linux-amd64.tar.gz" - - tar -C "${HOME}/.local" -xf "go${GO_VERSION}.linux-amd64.tar.gz" - - rm "go${GO_VERSION}.linux-amd64.tar.gz" - - export PATH="${HOME}/.local/go/bin:${PATH}" + # Verify installations + - echo "Verifying installations..." + - "echo Dart Sass: $(sass --version)" + - "echo Go: $(go version)" + - "echo Hugo: $(hugo version)" + - "echo Node.js: $(node --version)" - # Install Hugo - - echo "Installing Hugo ${HUGO_VERSION}..." - - curl -sLJO "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz" - - mkdir "${HOME}/.local/hugo" - - tar -C "${HOME}/.local/hugo" -xf "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz" - - rm "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz" - - export PATH="${HOME}/.local/hugo:${PATH}" + # Install Node.js dependencies + - echo "Installing Node.js dependencies..." + - "[[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci --prefer-offline || true" - # Verify installations - - echo "Verifying installations..." - - "echo Dart Sass: $(sass --version)" - - "echo Go: $(go version)" - - "echo Hugo: $(hugo version)" - - "echo Node.js: $(node --version)" + # Configure Git + - echo "Configuring Git..." + - git config core.quotepath false + build: + commands: + - echo "Building site..." + - hugo --gc --minify + artifacts: + baseDirectory: public + files: + - '**/*' + cache: + paths: + - ${HUGO_CACHEDIR}/**/* + - ${NPM_CONFIG_CACHE}/**/* + ``` - # Install Node.js dependencies - - echo "Installing Node.js dependencies..." - - "[[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci --prefer-offline || true" +Step 3 +: Commit and push the change to your GitHub repository. - # Configure Git - - echo "Configuring Git..." - - git config core.quotepath false - build: - commands: - - echo "Building site..." - - hugo --gc --minify - artifacts: - baseDirectory: public - files: - - '**/*' - cache: - paths: - - ${HUGO_CACHEDIR}/**/* - - ${NPM_CONFIG_CACHE}/**/* -``` + ```sh + git add -A + git commit -m "Create amplify.yml" + git push + ``` -### Step 3 +Step 4 +: Log in to your AWS account, navigate to the [Amplify Console], then press the **Deploy an app** button. -Commit and push the change to your GitHub repository. - -```sh -git add -A -git commit -m "Create amplify.yml" -git push -``` - -### Step 4 - -Log in to your AWS account, navigate to the [Amplify Console], then press the **Deploy an app** button. - -[Amplify Console]: https://console.aws.amazon.com/amplify/apps - -### Step 5 - -Choose a source code provider, then press the **Next** button. +Step 5 +: Choose a source code provider, then press the **Next** button. ![screen capture](amplify-step-05.png) -### Step 6 - -Authorize AWS Amplify to access your GitHub account. +Step 6 +: Authorize AWS Amplify to access your GitHub account. ![screen capture](amplify-step-06.png) -### Step 7 - -Select your personal account or relevant organization. +Step 7 +: Select your personal account or relevant organization. ![screen capture](amplify-step-07.png) -### Step 8 - -Authorize access to one or more repositories. +Step 8 +: Authorize access to one or more repositories. ![screen capture](amplify-step-08.png) -### Step 9 - -Select a repository and branch, then press the **Next** button. +Step 9 +: Select a repository and branch, then press the **Next** button. ![screen capture](amplify-step-09.png) -### Step 10 +Step 10 +: On the "App settings" page, scroll to the bottom then press the **Next** button. Amplify reads the `amplify.yml` file you created in Steps 1-3 instead of using the values on this page. -On the "App settings" page, scroll to the bottom then press the **Next** button. Amplify reads the `amplify.yml` file you created in Steps 1-3 instead of using the values on this page. +Step 11 +: On the "Review" page, scroll to the bottom then press the **Save and deploy** button. -### Step 11 - -On the "Review" page, scroll to the bottom then press the **Save and deploy** button. - -### Step 12 - -When your site has finished deploying, press the **Visit deployed URL** button to view your published site. +Step 12 +: When your site has finished deploying, press the **Visit deployed URL** button to view your published site. ![screen capture](amplify-step-11.png) + +[Amplify Console]: https://console.aws.amazon.com/amplify/apps diff --git a/content/en/host-and-deploy/host-on-cloudflare/index.md b/content/en/host-and-deploy/host-on-cloudflare/index.md index aebd7b868..018c50f0a 100644 --- a/content/en/host-and-deploy/host-on-cloudflare/index.md +++ b/content/en/host-and-deploy/host-on-cloudflare/index.md @@ -21,156 +21,146 @@ Please complete the following tasks before continuing: ## Procedure -### Step 1 +Step 1 +: Create a `wrangler.toml` file in the root of your project. -Create a `wrangler.toml` file in the root of your project. + ```toml {file="wrangler.toml" copy=true} + # Configure Cloudflare Worker -```toml {file="wrangler.toml" copy=true} -# Configure Cloudflare Worker + name = "hosting-cloudflare-worker" + compatibility_date = "2025-07-31" -name = "hosting-cloudflare-worker" -compatibility_date = "2025-07-31" + [build] + command = "chmod a+x build.sh && ./build.sh" -[build] -command = "chmod a+x build.sh && ./build.sh" + [assets] + directory = "./public" + not_found_handling = "404" + ``` -[assets] -directory = "./public" -not_found_handling = "404" -``` +Step 2 +: Create a `build.sh` file in the root of your project. -### Step 2 + ```sh {file="build.sh" copy=true} + #!/usr/bin/env bash -Create a `build.sh` file in the root of your project. + #------------------------------------------------------------------------------ + # @file + # Builds a Hugo site hosted on a Cloudflare Worker. + # + # The Cloudflare Worker automatically installs Node.js dependencies. + #------------------------------------------------------------------------------ -```sh {file="build.sh" copy=true} -#!/usr/bin/env bash + main() { -#------------------------------------------------------------------------------ -# @file -# Builds a Hugo site hosted on a Cloudflare Worker. -# -# The Cloudflare Worker automatically installs Node.js dependencies. -#------------------------------------------------------------------------------ + DART_SASS_VERSION=1.90.0 + GO_VERSION=1.24.5 + HUGO_VERSION=0.148.2 + NODE_VERSION=22.18.0 -main() { + export TZ=Europe/Oslo - DART_SASS_VERSION=1.90.0 - GO_VERSION=1.24.5 - HUGO_VERSION=0.148.2 - NODE_VERSION=22.18.0 + # Install Dart Sass + echo "Installing Dart Sass ${DART_SASS_VERSION}..." + curl -sLJO "https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz" + tar -C "${HOME}/.local" -xf "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz" + rm "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz" + export PATH="${HOME}/.local/dart-sass:${PATH}" - export TZ=Europe/Oslo + # Install Go + echo "Installing Go ${GO_VERSION}..." + curl -sLJO "https://go.dev/dl/go${GO_VERSION}.linux-amd64.tar.gz" + tar -C "${HOME}/.local" -xf "go${GO_VERSION}.linux-amd64.tar.gz" + rm "go${GO_VERSION}.linux-amd64.tar.gz" + export PATH="${HOME}/.local/go/bin:${PATH}" - # Install Dart Sass - echo "Installing Dart Sass ${DART_SASS_VERSION}..." - curl -sLJO "https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz" - tar -C "${HOME}/.local" -xf "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz" - rm "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz" - export PATH="${HOME}/.local/dart-sass:${PATH}" + # Install Hugo + echo "Installing Hugo ${HUGO_VERSION}..." + curl -sLJO "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz" + mkdir "${HOME}/.local/hugo" + tar -C "${HOME}/.local/hugo" -xf "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz" + rm "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz" + export PATH="${HOME}/.local/hugo:${PATH}" - # Install Go - echo "Installing Go ${GO_VERSION}..." - curl -sLJO "https://go.dev/dl/go${GO_VERSION}.linux-amd64.tar.gz" - tar -C "${HOME}/.local" -xf "go${GO_VERSION}.linux-amd64.tar.gz" - rm "go${GO_VERSION}.linux-amd64.tar.gz" - export PATH="${HOME}/.local/go/bin:${PATH}" + # Install Node.js + echo "Installing Node.js ${NODE_VERSION}..." + curl -sLJO "https://nodejs.org/dist/v${NODE_VERSION}/node-v${NODE_VERSION}-linux-x64.tar.xz" + tar -C "${HOME}/.local" -xf "node-v${NODE_VERSION}-linux-x64.tar.xz" + rm "node-v${NODE_VERSION}-linux-x64.tar.xz" + export PATH="${HOME}/.local/node-v${NODE_VERSION}-linux-x64/bin:${PATH}" - # Install Hugo - echo "Installing Hugo ${HUGO_VERSION}..." - curl -sLJO "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz" - mkdir "${HOME}/.local/hugo" - tar -C "${HOME}/.local/hugo" -xf "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz" - rm "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz" - export PATH="${HOME}/.local/hugo:${PATH}" + # Verify installations + echo "Verifying installations..." + echo Dart Sass: "$(sass --version)" + echo Go: "$(go version)" + echo Hugo: "$(hugo version)" + echo Node.js: "$(node --version)" - # Install Node.js - echo "Installing Node.js ${NODE_VERSION}..." - curl -sLJO "https://nodejs.org/dist/v${NODE_VERSION}/node-v${NODE_VERSION}-linux-x64.tar.xz" - tar -C "${HOME}/.local" -xf "node-v${NODE_VERSION}-linux-x64.tar.xz" - rm "node-v${NODE_VERSION}-linux-x64.tar.xz" - export PATH="${HOME}/.local/node-v${NODE_VERSION}-linux-x64/bin:${PATH}" + # Configure Git + echo "Configuring Git..." + git config core.quotepath false + if [ "$(git rev-parse --is-shallow-repository)" = "true" ]; then + git fetch --unshallow + fi - # Verify installations - echo "Verifying installations..." - echo Dart Sass: "$(sass --version)" - echo Go: "$(go version)" - echo Hugo: "$(hugo version)" - echo Node.js: "$(node --version)" + # Build the site + echo "Building the site..." + hugo --gc --minify - # Configure Git - echo "Configuring Git..." - git config core.quotepath false - if [ "$(git rev-parse --is-shallow-repository)" = "true" ]; then - git fetch --unshallow - fi + } - # Build the site - echo "Building the site..." - hugo --gc --minify + set -euo pipefail + main "$@" + ``` -} +Step 3 +: Commit the changes to your local Git repository and push to your GitHub repository. -set -euo pipefail -main "$@" -``` +Step 4 +: In the upper right corner of the Cloudflare [dashboard](https://dash.cloudflare.com/), press the **Add** button and select "Workers" from the drop down menu. -### Step 3 + ![screen capture](cloudflare-01.png) -Commit the changes to your local Git repository and push to your GitHub repository. +Step 5 +: On the "Workers" tab, press the **Get started** button to the right of the "Import a repository" item. -### Step 4 + ![screen capture](cloudflare-02.png) -In the upper right corner of the Cloudflare [dashboard](https://dash.cloudflare.com/), press the **Add** button and select "Workers" from the drop down menu. +Step 6 +: Connect to GitHub. -![screen capture](cloudflare-01.png) + ![screen capture](cloudflare-03.png) -### Step 5 +Step 7 +: Select the GitHub account where you want to install the Cloudflare Workers and Pages application. -On the "Workers" tab, press the **Get started** button to the right of the "Import a repository" item. + ![screen capture](cloudflare-04.png) -![screen capture](cloudflare-02.png) +Step 8 +: Authorize the Cloudflare Workers and Pages application to access all repositories or only select repositories, then press the **Install & Authorize** button. -### Step 6 + ![screen capture](cloudflare-05.png) -Connect to GitHub. + Your browser will be redirected to the Cloudflare dashboard. -![screen capture](cloudflare-03.png) +Step 9 +: On the "Workers" tab, press the **Get started** button to the right of the "Import a repository" item. -### Step 7 + ![screen capture](cloudflare-02.png) -Select the GitHub account where you want to install the Cloudflare Workers and Pages application. +Step 10 +: Select the repository to import. -![screen capture](cloudflare-04.png) + ![screen capture](cloudflare-06.png) -### Step 8 +Step 11 +: On the "Set up your application" screen, provide a project name, leave the build command blank, then press the **Create and deploy** button. -Authorize the Cloudflare Workers and Pages application to access all repositories or only select repositories, then press the **Install & Authorize** button. + ![screen capture](cloudflare-07.png) -![screen capture](cloudflare-05.png) +Step 12 +: Wait for the site to build and deploy, then visit your site. -Your browser will be redirected to the Cloudflare dashboard. + ![screen capture](cloudflare-08.png) -### Step 9 - -On the "Workers" tab, press the **Get started** button to the right of the "Import a repository" item. - -![screen capture](cloudflare-02.png) - -### Step 10 - -Select the repository to import. - -![screen capture](cloudflare-06.png) - -### Step 11 - -On the "Set up your application" screen, provide a project name, leave the build command blank, then press the **Create and deploy** button. - -![screen capture](cloudflare-07.png) - -### Step 12 - -Wait for the site to build and deploy, then visit your site. - -![screen capture](cloudflare-08.png) +In the future, whenever you push a change from your local Git repository, Cloudflare will rebuild and deploy your site. diff --git a/content/en/host-and-deploy/host-on-github-pages/gh-pages-1.png b/content/en/host-and-deploy/host-on-github-pages/gh-pages-01.png similarity index 100% rename from content/en/host-and-deploy/host-on-github-pages/gh-pages-1.png rename to content/en/host-and-deploy/host-on-github-pages/gh-pages-01.png diff --git a/content/en/host-and-deploy/host-on-github-pages/gh-pages-2.png b/content/en/host-and-deploy/host-on-github-pages/gh-pages-02.png similarity index 100% rename from content/en/host-and-deploy/host-on-github-pages/gh-pages-2.png rename to content/en/host-and-deploy/host-on-github-pages/gh-pages-02.png diff --git a/content/en/host-and-deploy/host-on-github-pages/gh-pages-3.png b/content/en/host-and-deploy/host-on-github-pages/gh-pages-03.png similarity index 100% rename from content/en/host-and-deploy/host-on-github-pages/gh-pages-3.png rename to content/en/host-and-deploy/host-on-github-pages/gh-pages-03.png diff --git a/content/en/host-and-deploy/host-on-github-pages/gh-pages-4.png b/content/en/host-and-deploy/host-on-github-pages/gh-pages-04.png similarity index 100% rename from content/en/host-and-deploy/host-on-github-pages/gh-pages-4.png rename to content/en/host-and-deploy/host-on-github-pages/gh-pages-04.png diff --git a/content/en/host-and-deploy/host-on-github-pages/gh-pages-5.png b/content/en/host-and-deploy/host-on-github-pages/gh-pages-05.png similarity index 100% rename from content/en/host-and-deploy/host-on-github-pages/gh-pages-5.png rename to content/en/host-and-deploy/host-on-github-pages/gh-pages-05.png diff --git a/content/en/host-and-deploy/host-on-github-pages/index.md b/content/en/host-and-deploy/host-on-github-pages/index.md index e708cffd3..dd4039dd8 100644 --- a/content/en/host-and-deploy/host-on-github-pages/index.md +++ b/content/en/host-and-deploy/host-on-github-pages/index.md @@ -6,14 +6,6 @@ keywords: [] aliases: [/hosting-and-deployment/hosting-on-github/] --- -## Prerequisites - -Please complete the following tasks before continuing: - -1. [Create a GitHub account] -1. [Install Git] -1. [Create a Hugo site] and test it locally with `hugo server`. - ## Types of sites There are three types of GitHub Pages sites: project, user, and organization. Project sites are connected to a specific project hosted on GitHub. User and organization sites are connected to a specific account on GitHub.com. @@ -21,200 +13,177 @@ There are three types of GitHub Pages sites: project, user, and organization. Pr > [!note] > See the [GitHub Pages documentation] to understand the requirements for repository ownership and naming. +## Prerequisites + +Please complete the following tasks before continuing: + +1. [Create](https://github.com/signup) a GitHub account +1. [Log in](https://github.com/login) to your GitHub account +1. [Create](https://github.com/new) a GitHub repository for your project +1. [Create](https://git-scm.com/docs/git-init) a local Git repository for your project with a [remote](https://git-scm.com/docs/git-remote) reference to your GitHub repository +1. Create a Hugo site within your local Git repository and test it with the `hugo server` command +1. Commit the changes to your local Git repository and push to your GitHub repository + ## Procedure -### Step 1 +Step 1 +: Visit your GitHub repository. From the main menu choose **Settings** > **Pages**. In the center of your screen you will see this: -Create a GitHub repository. + ![screen capture](gh-pages-01.png) -### Step 2 + Change the **Source** to `GitHub Actions`. The change is immediate; you do not have to press a Save button. -Push your local repository to GitHub. + ![screen capture](gh-pages-02.png) -### Step 3 +Step 2 +: In your site configuration, change the location of the image cache to the [`cacheDir`] as shown below: -Visit your GitHub repository. From the main menu choose **Settings** > **Pages**. In the center of your screen you will see this: + {{< code-toggle file=hugo copy=true >}} + [caches.images] + dir = ":cacheDir/images" + {{< /code-toggle >}} -![screen capture](gh-pages-1.png) -{style="max-width: 280px"} + See [configure file caches] for more information. -### Step 4 +Step 3 +: Create a file named `hugo.yaml` in a directory named `.github/workflows`. -Change the **Source** to `GitHub Actions`. The change is immediate; you do not have to press a Save button. + ```text + mkdir -p .github/workflows + touch .github/workflows/hugo.yaml + ``` -![screen capture](gh-pages-2.png) -{style="max-width: 280px"} +Step 4 +: Copy and paste the YAML below into the file you created. -### Step 5 + ```yaml {file=".github/workflows/hugo.yaml" copy=true} + name: Build and deploy + on: + push: + branches: + - main + workflow_dispatch: + permissions: + contents: read + pages: write + id-token: write + concurrency: + group: pages + cancel-in-progress: false + defaults: + run: + shell: bash + jobs: + build: + runs-on: ubuntu-latest + env: + DART_SASS_VERSION: 1.90.0 + GO_VERSION: 1.24.5 + HUGO_VERSION: 0.148.2 + NODE_VERSION: 22.18.0 + TZ: Europe/Oslo + steps: + - name: Checkout + uses: actions/checkout@v5 + with: + submodules: recursive + fetch-depth: 0 + - name: Setup Go + uses: actions/setup-go@v5 + with: + go-version: ${{ env.GO_VERSION }} + cache: false + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: ${{ env.NODE_VERSION }} + - name: Setup Pages + id: pages + uses: actions/configure-pages@v5 + - name: Create directory for user-specific executable files + run: | + mkdir -p "${HOME}/.local" + - name: Install Dart Sass + run: | + curl -sLJO "https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz" + tar -C "${HOME}/.local" -xf "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz" + rm "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz" + echo "${HOME}/.local/dart-sass" >> "${GITHUB_PATH}" + - name: Install Hugo + run: | + curl -sLJO "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz" + mkdir "${HOME}/.local/hugo" + tar -C "${HOME}/.local/hugo" -xf "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz" + rm "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz" + echo "${HOME}/.local/hugo" >> "${GITHUB_PATH}" + - name: Verify installations + run: | + echo "Dart Sass: $(sass --version)" + echo "Go: $(go version)" + echo "Hugo: $(hugo version)" + echo "Node.js: $(node --version)" + - name: Install Node.js dependencies + run: | + [[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci || true + - name: Configure Git + run: | + git config core.quotepath false + - name: Cache restore + id: cache-restore + uses: actions/cache/restore@v4 + with: + path: ${{ runner.temp }}/hugo_cache + key: hugo-${{ github.run_id }} + restore-keys: + hugo- + - name: Build the site + run: | + hugo \ + --gc \ + --minify \ + --baseURL "${{ steps.pages.outputs.base_url }}/" \ + --cacheDir "${{ runner.temp }}/hugo_cache" + - name: Cache save + id: cache-save + uses: actions/cache/save@v4 + with: + path: ${{ runner.temp }}/hugo_cache + key: ${{ steps.cache-restore.outputs.cache-primary-key }} + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + with: + path: ./public + 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@v4 + ``` -In your site configuration, change the location of the image cache to the [`cacheDir`] as shown below: +Step 5 +: Commit the changes to your local Git repository and push to your GitHub repository. -{{< code-toggle file=hugo >}} -[caches.images] -dir = ":cacheDir/images" -{{< /code-toggle >}} +Step 6 +: From GitHub's main menu, choose **Actions**. You will see something like this: -See [configure file caches] for more information. + ![screen capture](gh-pages-03.png) -### Step 6 +Step 7 +: When GitHub has finished building and deploying your site, the color of the status indicator will change to green. -Create a file named `hugo.yaml` in a directory named `.github/workflows`. + ![screen capture](gh-pages-04.png) -```text -mkdir -p .github/workflows -touch .github/workflows/hugo.yaml -``` +Step 8 +: Click on the commit message as shown above. Under the deploy step, you will see a link to your live site. -### Step 7 + ![screen capture](gh-pages-05.png) -> [!note] -> The workflow below ensures Hugo's `cacheDir` is persistent, preserving modules, processed images, and [`resources.GetRemote`] data between builds. - -Copy and paste the YAML below into the file you created. Change the branch name and Hugo version as needed. - -```yaml {file=".github/workflows/hugo.yaml" copy=true} -name: Build and deploy -on: - push: - branches: - - main - workflow_dispatch: -permissions: - contents: read - pages: write - id-token: write -concurrency: - group: pages - cancel-in-progress: false -defaults: - run: - shell: bash -jobs: - build: - runs-on: ubuntu-latest - env: - DART_SASS_VERSION: 1.90.0 - GO_VERSION: 1.24.5 - HUGO_VERSION: 0.148.2 - NODE_VERSION: 22.18.0 - TZ: Europe/Oslo - steps: - - name: Checkout - uses: actions/checkout@v5 - with: - submodules: recursive - fetch-depth: 0 - - name: Setup Go - uses: actions/setup-go@v5 - with: - go-version: ${{ env.GO_VERSION }} - cache: false - - name: Setup Node.js - uses: actions/setup-node@v4 - with: - node-version: ${{ env.NODE_VERSION }} - - name: Setup Pages - id: pages - uses: actions/configure-pages@v5 - - name: Create directory for user-specific executable files - run: | - mkdir -p "${HOME}/.local" - - name: Install Dart Sass - run: | - curl -sLJO "https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz" - tar -C "${HOME}/.local" -xf "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz" - rm "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz" - echo "${HOME}/.local/dart-sass" >> "${GITHUB_PATH}" - - name: Install Hugo - run: | - curl -sLJO "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz" - mkdir "${HOME}/.local/hugo" - tar -C "${HOME}/.local/hugo" -xf "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz" - rm "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz" - echo "${HOME}/.local/hugo" >> "${GITHUB_PATH}" - - name: Verify installations - run: | - echo "Dart Sass: $(sass --version)" - echo "Go: $(go version)" - echo "Hugo: $(hugo version)" - echo "Node.js: $(node --version)" - - name: Install Node.js dependencies - run: | - [[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci || true - - name: Configure Git - run: | - git config core.quotepath false - - name: Cache restore - id: cache-restore - uses: actions/cache/restore@v4 - with: - path: ${{ runner.temp }}/hugo_cache - key: hugo-${{ github.run_id }} - restore-keys: - hugo- - - name: Build the site - run: | - hugo \ - --gc \ - --minify \ - --baseURL "${{ steps.pages.outputs.base_url }}/" \ - --cacheDir "${{ runner.temp }}/hugo_cache" - - name: Cache save - id: cache-save - uses: actions/cache/save@v4 - with: - path: ${{ runner.temp }}/hugo_cache - key: ${{ steps.cache-restore.outputs.cache-primary-key }} - - name: Upload artifact - uses: actions/upload-pages-artifact@v3 - with: - path: ./public - 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@v4 -``` - -### Step 8 - -Commit and push the change to your GitHub repository. - -```sh -git add -A -git commit -m "Create hugo.yaml" -git push -``` - -### Step 9 - -From GitHub's main menu, choose **Actions**. You will see something like this: - -![screen capture](gh-pages-3.png) -{style="max-width: 350px"} - -### Step 10 - -When GitHub has finished building and deploying your site, the color of the status indicator will change to green. - -![screen capture](gh-pages-4.png) -{style="max-width: 350px"} - -### Step 11 - -Click on the commit message as shown above. You will see this: - -![screen capture](gh-pages-5.png) -{style="max-width: 611px"} - -Under the deploy step, you will see a link to your live site. - -In the future, whenever you push a change from your local repository, GitHub will rebuild your site and deploy the changes. +In the future, whenever you push a change from your local Git repository, GitHub Pages will rebuild and deploy your site. ## Customize the workflow @@ -233,11 +202,7 @@ You may remove this step if your site, themes, and modules do not transpile Sass - [Caching dependencies to speed up workflows](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows) - [Manage a custom domain for your GitHub Pages site](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/about-custom-domains-and-github-pages) -[Create a GitHub account]: https://github.com/signup -[Create a Hugo site]: /getting-started/quick-start/ +[`cacheDir`]: /configuration/all/#cachedir +[configure file caches]: /configuration/caches/ [Dart Sass]: /functions/css/sass/#dart-sass [GitHub Pages documentation]: https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages#types-of-github-pages-sites -[Install Git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git -[`cacheDir`]: /configuration/all/#cachedir -[`resources.GetRemote`]: /functions/resources/getremote/ -[configure file caches]: /configuration/caches/ diff --git a/content/en/host-and-deploy/host-on-netlify/index.md b/content/en/host-and-deploy/host-on-netlify/index.md index b88a1aa3a..cc0bf6b2b 100644 --- a/content/en/host-and-deploy/host-on-netlify/index.md +++ b/content/en/host-and-deploy/host-on-netlify/index.md @@ -6,104 +6,85 @@ keywords: [] aliases: [/hosting-and-deployment/hosting-on-netlify/] --- +Use these instructions to enable continuous deployment from a GitHub repository. The same general steps apply if you are using Azure DevOps, Bitbucket, or GitLab for version control. + ## Prerequisites Please complete the following tasks before continuing: -1. [Create a Netlify account] -1. [Install Git] -1. [Create a Hugo site] and test it locally with `hugo server` -1. Commit the changes to your local repository -1. Push the local repository to your [GitHub], [GitLab], or [Bitbucket] account - -[Bitbucket]: https://bitbucket.org/product -[Create a Hugo site]: /getting-started/quick-start/ -[Create a Netlify account]: https://app.netlify.com/signup -[GitHub]: https://github.com -[GitLab]: https://about.gitlab.com/ -[Install Git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git +1. [Create](https://app.netlify.com/signup) a Netlify account +1. [Log in](https://app.netlify.com/login) to your Netlify account +1. [Create](https://github.com/signup) a GitHub account +1. [Log in](https://github.com/login) to your GitHub account +1. [Create](https://github.com/new) a GitHub repository for your project +1. [Create](https://git-scm.com/docs/git-init) a local Git repository for your project with a [remote](https://git-scm.com/docs/git-remote) reference to your GitHub repository +1. Create a Hugo site within your local Git repository and test it with the `hugo server` command +1. Commit the changes to your local Git repository and push to your GitHub repository. ## Procedure -This procedure will enable continuous deployment from a GitHub repository. The procedure is essentially the same if you are using GitLab or Bitbucket. +Step 1 +: Log in to your Netlify account, navigate to the Sites page, press the **Add new site** button, and choose "Import an existing project" from the dropdown menu. -### Step 1 +Step 2 +: Select your deployment method. -Log in to your Netlify account, navigate to the Sites page, press the **Add new site** button, and choose "Import an existing project" from the dropdown menu. + ![screen capture](netlify-step-02.png) -### Step 2 +Step 3 +: Authorize Netlify to connect with your GitHub account by pressing the **Authorize Netlify** button. -Select your deployment method. + ![screen capture](netlify-step-03.png) -![screen capture](netlify-step-02.png) +Step 4 +: Press the **Configure Netlify on GitHub** button. -### Step 3 + ![screen capture](netlify-step-04.png) -Authorize Netlify to connect with your GitHub account by pressing the **Authorize Netlify** button. +Step 5 +: Install the Netlify app by selecting your GitHub account. -![screen capture](netlify-step-03.png) + ![screen capture](netlify-step-05.png) -### Step 4 +Step 6 +: Press the **Install** button. -Press the **Configure Netlify on GitHub** button. + ![screen capture](netlify-step-06.png) -![screen capture](netlify-step-04.png) +Step 7 +: Click on the site's repository from the list. -### Step 5 + ![screen capture](netlify-step-07.png) -Install the Netlify app by selecting your GitHub account. +Step 8 +: Set the site name and branch from which to deploy. -![screen capture](netlify-step-05.png) + ![screen capture](netlify-step-08.png) -### Step 6 +Step 9 +: Define the build settings, press the **Add environment variables** button, then press the **New variable** button. -Press the **Install** button. + ![screen capture](netlify-step-09.png) -![screen capture](netlify-step-06.png) +Step 10 +: Create a new environment variable named `HUGO_VERSION` and set the value to the [latest version](https://github.com/gohugoio/hugo/releases/latest). -### Step 7 + ![screen capture](netlify-step-10.png) -Click on the site's repository from the list. +Step 11 +: Press the "Deploy my new site" button at the bottom of the page. -![screen capture](netlify-step-07.png) + ![screen capture](netlify-step-11.png) -### Step 8 +Step 12 +: At the bottom of the screen, wait for the deploy to complete, then click on the deploy log entry. -Set the site name and branch from which to deploy. + ![screen capture](netlify-step-12.png) -![screen capture](netlify-step-08.png) +Step 13 +: Press the **Open production deploy** button to view the live site. -### Step 9 - -Define the build settings, press the **Add environment variables** button, then press the **New variable** button. - -![screen capture](netlify-step-09.png) - -### Step 10 - -Create a new environment variable named `HUGO_VERSION` and set the value to the [latest version]. - -[latest version]: https://github.com/gohugoio/hugo/releases/latest - -![screen capture](netlify-step-10.png) - -### Step 11 - -Press the "Deploy my new site" button at the bottom of the page. - -![screen capture](netlify-step-11.png) - -### Step 12 - -At the bottom of the screen, wait for the deploy to complete, then click on the deploy log entry. - -![screen capture](netlify-step-12.png) - -### Step 13 - -Press the **Open production deploy** button to view the live site. - -![screen capture](netlify-step-13.png) + ![screen capture](netlify-step-13.png) ## Configuration file diff --git a/content/en/host-and-deploy/host-on-render/index.md b/content/en/host-and-deploy/host-on-render/index.md index f1190aae2..f52e09280 100644 --- a/content/en/host-and-deploy/host-on-render/index.md +++ b/content/en/host-and-deploy/host-on-render/index.md @@ -6,7 +6,7 @@ keywords: [] aliases: [/hosting-and-deployment/hosting-on-render/] --- -Use these instructions to enable continuous deployment from a GitHub repository. The same general steps apply if you are using GitLab or Bitbucket for version control. +Use these instructions to enable continuous deployment from a GitHub repository. The same general steps apply if you are using Bitbucket or GitLab for version control. ## Prerequisites @@ -22,160 +22,149 @@ Please complete the following tasks before continuing: ## Procedure -### Step 1 +Step 1 +: Create a [Render Blueprint][] in the root of your project. -Create a [Render Blueprint][] in the root of your project. + ``` {file="render.yaml" copy=true} + services: + - type: web + name: hosting-render + repo: https://github.com/jmooring/hosting-render + runtime: static + buildCommand: chmod a+x build.sh && ./build.sh + staticPublishPath: public + envVars: + - key: DART_SASS_VERSION + value: 1.90.0 + - key: GO_VERSION + value: 1.24.5 + - key: HUGO_VERSION + value: 0.148.2 + - key: NODE_VERSION + value: 22.18.0 + - key: TZ + value: Europe/Oslo + ``` -``` {file="render.yaml" copy=true} -services: - - type: web - name: hosting-render - repo: https://github.com/jmooring/hosting-render - runtime: static - buildCommand: chmod a+x build.sh && ./build.sh - staticPublishPath: public - envVars: - - key: DART_SASS_VERSION - value: 1.90.0 - - key: GO_VERSION - value: 1.24.5 - - key: HUGO_VERSION - value: 0.148.2 - - key: NODE_VERSION - value: 22.18.0 - - key: TZ - value: Europe/Oslo -``` +Step 2 +: Create a `build.sh` file in the root of your project. -### Step 2 + ```sh {file="build.sh" copy=true} + #!/usr/bin/env bash -Create a `build.sh` file in the root of your project. + #------------------------------------------------------------------------------ + # @file + # Builds a Hugo site hosted on a Render. + # + # Render automatically installs Node.js dependencies. + #------------------------------------------------------------------------------ -```sh {file="build.sh" copy=true} -#!/usr/bin/env bash + main() { -#------------------------------------------------------------------------------ -# @file -# Builds a Hugo site hosted on a Render. -# -# Render automatically installs Node.js dependencies. -#------------------------------------------------------------------------------ + # Create directory for user-specific executable files + echo "Creating directory for user-specific executable files..." + mkdir -p "${HOME}/.local" -main() { + # Install Dart Sass + echo "Installing Dart Sass ${DART_SASS_VERSION}..." + curl -sLJO "https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz" + tar -C "${HOME}/.local" -xf "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz" + rm "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz" + export PATH="${HOME}/.local/dart-sass:${PATH}" - # Create directory for user-specific executable files - echo "Creating directory for user-specific executable files..." - mkdir -p "${HOME}/.local" + # Install Go + echo "Installing Go ${GO_VERSION}..." + curl -sLJO "https://go.dev/dl/go${GO_VERSION}.linux-amd64.tar.gz" + tar -C "${HOME}/.local" -xf "go${GO_VERSION}.linux-amd64.tar.gz" + rm "go${GO_VERSION}.linux-amd64.tar.gz" + export PATH="${HOME}/.local/go/bin:${PATH}" - # Install Dart Sass - echo "Installing Dart Sass ${DART_SASS_VERSION}..." - curl -sLJO "https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz" - tar -C "${HOME}/.local" -xf "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz" - rm "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz" - export PATH="${HOME}/.local/dart-sass:${PATH}" + # Install Hugo + echo "Installing Hugo ${HUGO_VERSION}..." + curl -sLJO "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz" + mkdir -p "${HOME}/.local/hugo" + tar -C "${HOME}/.local/hugo" -xf "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz" + rm "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz" + export PATH="${HOME}/.local/hugo:${PATH}" - # Install Go - echo "Installing Go ${GO_VERSION}..." - curl -sLJO "https://go.dev/dl/go${GO_VERSION}.linux-amd64.tar.gz" - tar -C "${HOME}/.local" -xf "go${GO_VERSION}.linux-amd64.tar.gz" - rm "go${GO_VERSION}.linux-amd64.tar.gz" - export PATH="${HOME}/.local/go/bin:${PATH}" + # Verify installations + echo "Verifying installations..." + echo Dart Sass: "$(sass --version)" + echo Go: "$(go version)" + echo Hugo: "$(hugo version)" + echo Node.js: "$(node --version)" - # Install Hugo - echo "Installing Hugo ${HUGO_VERSION}..." - curl -sLJO "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz" - mkdir -p "${HOME}/.local/hugo" - tar -C "${HOME}/.local/hugo" -xf "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz" - rm "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz" - export PATH="${HOME}/.local/hugo:${PATH}" + # Configure Git + echo "Configuring Git..." + git config core.quotepath false + if [ "$(git rev-parse --is-shallow-repository)" = "true" ]; then + git fetch --unshallow + fi - # Verify installations - echo "Verifying installations..." - echo Dart Sass: "$(sass --version)" - echo Go: "$(go version)" - echo Hugo: "$(hugo version)" - echo Node.js: "$(node --version)" + # Build the site + echo "Building the site..." + hugo --gc --minify --baseURL "${RENDER_EXTERNAL_URL}" - # Configure Git - echo "Configuring Git..." - git config core.quotepath false - if [ "$(git rev-parse --is-shallow-repository)" = "true" ]; then - git fetch --unshallow - fi + } - # Build the site - echo "Building the site..." - hugo --gc --minify --baseURL "${RENDER_EXTERNAL_URL}" + set -euo pipefail + main "$@" + ``` -} +Step 3 +: Commit the changes to your local Git repository and push to your GitHub repository. -set -euo pipefail -main "$@" -``` +Step 4 +: On the Render [dashboard][], press the **Add new** button and select "Blueprint" from the drop-down menu. -### Step 3 + ![screen capture](render-01.png) -Commit the changes to your local Git repository and push to your GitHub repository. +Step 5 +: Press the **GitHub** button to connect to your GitHub account. -### Step 4 + ![screen capture](render-02.png) -On the Render [dashboard][], press the **Add new** button and select "Blueprint" from the drop-down menu. +Step 6 +: Press the **Authorize Render** button to allow the Render application to access your GitHub account. -![screen capture](render-01.png) + ![screen capture](render-03.png) -### Step 5 +Step 7 +: Select the GitHub account where you want to install the Render application. -Press the **GitHub** button to connect to your GitHub account. + ![screen capture](render-04.png) -![screen capture](render-02.png) - -### Step 6 - -Press the **Authorize Render** button to allow the Render application to access your GitHub account. - -![screen capture](render-03.png) - -### Step 7 - -Select the GitHub account where you want to install the Render application. - -![screen capture](render-04.png) - -### Step 8 - -Authorize the Render application to access all repositories or only select repositories, then press the **Install** button. +Step 8 +: Authorize the Render application to access all repositories or only select repositories, then press the **Install** button. ![screen capture](render-05.png) -### Step 9 +Step 9 +: On the "Create a new Blueprint Instance in My Workspacee" page, press the **Connect** button to the right of the name of your GitHub repository. -On the "Create a new Blueprint Instance in My Workspacee" page, press the **Connect** button to the right of the name of your GitHub repository. + ![screen capture](render-06.png) -![screen capture](render-06.png) +Step 10 +: Enter a unique name for your Blueprint, then press the **Deploy Blueprint** button at the bottom of the page. -### Step 10 + ![screen capture](render-07.png) -Enter a unique name for your Blueprint, then press the **Deploy Blueprint** button at the bottom of the page. +Step 11 +: Wait for the site to build and deploy, then click on the "Resources" link on the left side of the page. -![screen capture](render-07.png) + ![screen capture](render-08.png) -### Step 11 +Step 12 +: Click on the link to the static site resource. -Wait for the site to build and deploy, then click on the "Resources" link on the left side of the page. + ![screen capture](render-09.png) -![screen capture](render-08.png) +Step 13 +: Click on the link to your published site. -### Step 12 + ![screen capture](render-10.png) -Click on the link to the static site resource. - -![screen capture](render-09.png) - -### Step 13 - -Click on the link to your published site. - -![screen capture](render-10.png) +In the future, whenever you push a change from your local Git repository, Render will rebuild and deploy your site. [Render Blueprint]: https://render.com/docs/blueprint-spec [dashboard]: https://dashboard.render.com/ diff --git a/content/en/host-and-deploy/host-on-vercel/index.md b/content/en/host-and-deploy/host-on-vercel/index.md index 2a48325e6..8d402cb87 100644 --- a/content/en/host-and-deploy/host-on-vercel/index.md +++ b/content/en/host-and-deploy/host-on-vercel/index.md @@ -5,7 +5,7 @@ categories: [] keywords: [] --- -Use these instructions to enable continuous deployment from a GitHub repository. The same general steps apply if you are using GitLab or Bitbucket for version control. +Use these instructions to enable continuous deployment from a GitHub repository. The same general steps apply if you are using Bitbucket or GitLab for version control. ## Prerequisites @@ -21,156 +21,145 @@ Please complete the following tasks before continuing: ## Procedure -### Step 1 +Step 1 +: Create a `vercel.json` file in the root of your project. -Create a `vercel.json` file in the root of your project. + ```json {file="vercel.json" copy=true} + { + "$schema": "https://openapi.vercel.sh/vercel.json", + "buildCommand": "chmod a+x build.sh && ./build.sh", + "outputDirectory": "public" + } + ``` -```json {file="vercel.json" copy=true} -{ - "$schema": "https://openapi.vercel.sh/vercel.json", - "buildCommand": "chmod a+x build.sh && ./build.sh", - "outputDirectory": "public" -} -``` +Step 2 +: Create a `build.sh` file in the root of your project. -### Step 2 + ```sh {file="build.sh" copy=true} + #!/usr/bin/env bash -Create a `build.sh` file in the root of your project. + #------------------------------------------------------------------------------ + # @file + # Builds a Hugo site hosted on Vercel. + # + # The Vercel build image automatically installs Node.js dependencies. + #------------------------------------------------------------------------------ -```sh {file="build.sh" copy=true} -#!/usr/bin/env bash + main() { -#------------------------------------------------------------------------------ -# @file -# Builds a Hugo site hosted on Vercel. -# -# The Vercel build image automatically installs Node.js dependencies. -#------------------------------------------------------------------------------ + DART_SASS_VERSION=1.90.0 + GO_VERSION=1.24.5 + HUGO_VERSION=0.148.2 + NODE_VERSION=22.18.0 -main() { + export TZ=Europe/Oslo - DART_SASS_VERSION=1.90.0 - GO_VERSION=1.24.5 - HUGO_VERSION=0.148.2 - NODE_VERSION=22.18.0 + # Install Dart Sass + echo "Installing Dart Sass ${DART_SASS_VERSION}..." + curl -sLJO "https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz" + tar -C "${HOME}/.local" -xf "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz" + rm "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz" + export PATH="${HOME}/.local/dart-sass:${PATH}" - export TZ=Europe/Oslo + # Install Go + echo "Installing Go ${GO_VERSION}..." + curl -sLJO "https://go.dev/dl/go${GO_VERSION}.linux-amd64.tar.gz" + tar -C "${HOME}/.local" -xf "go${GO_VERSION}.linux-amd64.tar.gz" + rm "go${GO_VERSION}.linux-amd64.tar.gz" + export PATH="${HOME}/.local/go/bin:${PATH}" - # Install Dart Sass - echo "Installing Dart Sass ${DART_SASS_VERSION}..." - curl -sLJO "https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz" - tar -C "${HOME}/.local" -xf "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz" - rm "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz" - export PATH="${HOME}/.local/dart-sass:${PATH}" + # Install Hugo + echo "Installing Hugo ${HUGO_VERSION}..." + curl -sLJO "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz" + mkdir "${HOME}/.local/hugo" + tar -C "${HOME}/.local/hugo" -xf "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz" + rm "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz" + export PATH="${HOME}/.local/hugo:${PATH}" - # Install Go - echo "Installing Go ${GO_VERSION}..." - curl -sLJO "https://go.dev/dl/go${GO_VERSION}.linux-amd64.tar.gz" - tar -C "${HOME}/.local" -xf "go${GO_VERSION}.linux-amd64.tar.gz" - rm "go${GO_VERSION}.linux-amd64.tar.gz" - export PATH="${HOME}/.local/go/bin:${PATH}" + # Install Node.js + echo "Installing Node.js ${NODE_VERSION}..." + curl -sLJO "https://nodejs.org/dist/v${NODE_VERSION}/node-v${NODE_VERSION}-linux-x64.tar.xz" + tar -C "${HOME}/.local" -xf "node-v${NODE_VERSION}-linux-x64.tar.xz" + rm "node-v${NODE_VERSION}-linux-x64.tar.xz" + export PATH="${HOME}/.local/node-v${NODE_VERSION}-linux-x64/bin:${PATH}" - # Install Hugo - echo "Installing Hugo ${HUGO_VERSION}..." - curl -sLJO "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz" - mkdir "${HOME}/.local/hugo" - tar -C "${HOME}/.local/hugo" -xf "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz" - rm "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz" - export PATH="${HOME}/.local/hugo:${PATH}" + # Verify installations + echo "Verifying installations..." + echo Dart Sass: "$(sass --version)" + echo Go: "$(go version)" + echo Hugo: "$(hugo version)" + echo Node.js: "$(node --version)" - # Install Node.js - echo "Installing Node.js ${NODE_VERSION}..." - curl -sLJO "https://nodejs.org/dist/v${NODE_VERSION}/node-v${NODE_VERSION}-linux-x64.tar.xz" - tar -C "${HOME}/.local" -xf "node-v${NODE_VERSION}-linux-x64.tar.xz" - rm "node-v${NODE_VERSION}-linux-x64.tar.xz" - export PATH="${HOME}/.local/node-v${NODE_VERSION}-linux-x64/bin:${PATH}" + # Configure Git + echo "Configuring Git..." + git config core.quotepath false + if [ "$(git rev-parse --is-shallow-repository)" = "true" ]; then + git fetch --unshallow + fi - # Verify installations - echo "Verifying installations..." - echo Dart Sass: "$(sass --version)" - echo Go: "$(go version)" - echo Hugo: "$(hugo version)" - echo Node.js: "$(node --version)" + # Build the site + echo "Building the site" + hugo --gc --minify --baseURL "https://${VERCEL_PROJECT_PRODUCTION_URL}" - # Configure Git - echo "Configuring Git..." - git config core.quotepath false - if [ "$(git rev-parse --is-shallow-repository)" = "true" ]; then - git fetch --unshallow - fi + } - # Build the site - echo "Building the site" - hugo --gc --minify --baseURL "https://${VERCEL_PROJECT_PRODUCTION_URL}" + set -euo pipefail + main "$@" + ``` -} +Step 3 +: Commit the changes to your local Git repository and push to your GitHub repository. -set -euo pipefail -main "$@" -``` +Step 4 +: In the upper right corner of the Vercel dashboard, press the **Add New** button and select "Project" from the drop down menu. -### Step 3 + ![screen capture](vercel-01.png) -Commit the changes to your local Git repository and push to your GitHub repository. +Step 5 +: Press the "Continue with GitHub" button. -### Step 4 + ![screen capture](vercel-02.png) -In the upper right corner of the Vercel dashboard, press the **Add New** button and select "Project" from the drop down menu. +Step 6 +: Press the **Authorize Vercel** button to allow the Vercel application to access your GitHub account. -![screen capture](vercel-01.png) + ![screen capture](vercel-03.png) -### Step 5 +Step 7 +: Press the **Install** button to install the Vercel application. -Press the "Continue with GitHub" button. + ![screen capture](vercel-04.png) -![screen capture](vercel-02.png) +Step 8 +: Select the GitHub account where you want to install the Vercel application. -### Step 6 + ![screen capture](vercel-05.png) -Press the **Authorize Vercel** button to allow the Vercel application to access your GitHub account. +Step 9 +: Authorize the Vercel application to access all repositories or only select repositories, then press the **Install** button. -![screen capture](vercel-03.png) + ![screen capture](vercel-06.png) -### Step 7 + Your browser will be redirected to the Cloudflare dashboard. -Press the **Install** button to install the Vercel application. +Step 10 +: Press the **Import** button to the right of the name of your GitHub repository. -![screen capture](vercel-04.png) + ![screen capture](vercel-07.png) -### Step 8 +Step 11 +: On the "New Project" page, leave the settings at their default values and press the **Deploy** button. -Select the GitHub account where you want to install the Vercel application. + ![screen capture](vercel-08.png) -![screen capture](vercel-05.png) +Step 12 +: When the deployment completes, press the **Continue to Dashboard" button at the bottom of the page. -### Step 9 + ![screen capture](vercel-09.png) -Authorize the Vercel application to access all repositories or only select repositories, then press the **Install** button. +Step 13 +: On the "Production Deployment" page, click on the link to your published site. -![screen capture](vercel-06.png) + ![screen capture](vercel-10.png) -Your browser will be redirected to the Cloudflare dashboard. - -### Step 10 - -Press the **Import** button to the right of the name of your GitHub repository. - -![screen capture](vercel-07.png) - -### Step 11 - -On the "New Project" page, leave the settings at their default values and press the **Deploy** button. - -![screen capture](vercel-08.png) - -### Step 12 - -When the deployment completes, press the **Continue to Dashboard" button at the bottom of the page. - -![screen capture](vercel-09.png) - -### Step 13 - -On the "Production Deployment" page, click on the link to your published site. - -![screen capture](vercel-10.png) +In the future, whenever you push a change from your local Git repository, Vercel will rebuild and deploy your site.