diff options
author | Bjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com> | 2022-03-08 19:39:33 +0100 |
---|---|---|
committer | Bjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com> | 2022-03-08 19:39:33 +0100 |
commit | 9d76b8fa34436d87ff023d95c39d60144ccd7f4d (patch) | |
tree | d157e6a0b8427ad4e3eb32e61a60c799f7d4f6d1 /docs/content/en | |
parent | 4576c82ed462bc9c3934f76181101df1c5a4157e (diff) | |
parent | d706529720b3b2ccb99719ccd578062ca25a0cc2 (diff) |
Merge commit 'd706529720b3b2ccb99719ccd578062ca25a0cc2'
Diffstat (limited to 'docs/content/en')
-rw-r--r-- | docs/content/en/content-management/build-options.md | 4 | ||||
-rw-r--r-- | docs/content/en/content-management/comments.md | 2 | ||||
-rw-r--r-- | docs/content/en/content-management/diagrams.md | 60 | ||||
-rw-r--r-- | docs/content/en/hosting-and-deployment/deployment-with-nanobox.md | 249 | ||||
-rw-r--r-- | docs/content/en/hosting-and-deployment/hosting-on-github.md | 10 | ||||
-rwxr-xr-x | docs/content/en/hugo-pipes/introduction.md | 17 | ||||
-rw-r--r-- | docs/content/en/news/0.15-relnotes/index.md | 2 | ||||
-rw-r--r-- | docs/content/en/news/0.20-relnotes/index.md | 2 | ||||
-rw-r--r-- | docs/content/en/news/0.22-relnotes/index.md | 2 | ||||
-rw-r--r-- | docs/content/en/news/0.46-relnotes/index.md | 2 |
10 files changed, 90 insertions, 260 deletions
diff --git a/docs/content/en/content-management/build-options.md b/docs/content/en/content-management/build-options.md index 93da7c421..c3f6f04c9 100644 --- a/docs/content/en/content-management/build-options.md +++ b/docs/content/en/content-management/build-options.md @@ -18,12 +18,12 @@ toc: true They are stored in a reserved Front Matter object named `_build` with the following defaults: -```yaml +{{< code-toggle >}} _build: render: always list: always publishResources: true -``` +{{< /code-toggle >}} #### render If `always`, the page will be treated as a published page, holding its dedicated output files (`index.html`, etc...) and permalink. diff --git a/docs/content/en/content-management/comments.md b/docs/content/en/content-management/comments.md index bbeb21ada..311f24c14 100644 --- a/docs/content/en/content-management/comments.md +++ b/docs/content/en/content-management/comments.md @@ -30,7 +30,7 @@ Hugo comes with all the code you need to load Disqus into your templates. Before Disqus comments require you set a single value in your [site's configuration file][configuration] like so: {{< code-toggle copy="false" >}} -disqusShortname = "yourdiscussshortname" +disqusShortname = "yourDisqusShortname" {{</ code-toggle >}} For many websites, this is enough configuration. However, you also have the option to set the following in the [front matter][] of a single content file: diff --git a/docs/content/en/content-management/diagrams.md b/docs/content/en/content-management/diagrams.md index 4e3f6164b..cfc0b3644 100644 --- a/docs/content/en/content-management/diagrams.md +++ b/docs/content/en/content-management/diagrams.md @@ -12,8 +12,68 @@ toc: true --- +{{< new-in "0.93.0" >}} + + +## GoAT Diagrams (Ascii) + +Hugo supports [GoAT](https://github.com/bep/goat) natively. This means that this code block: + +```` +```goat + . . . .--- 1 .-- 1 / 1 + / \ | | .---+ .-+ + + / \ .---+---. .--+--. | '--- 2 | '-- 2 / \ 2 + + + | | | | ---+ ---+ + + / \ / \ .-+-. .-+-. .+. .+. | .--- 3 | .-- 3 \ / 3 + / \ / \ | | | | | | | | '---+ '-+ + + 1 2 3 4 1 2 3 4 1 2 3 4 '--- 4 '-- 4 \ 4 + +``` +```` + +Will be rendered as: + +```goat + + . . . .--- 1 .-- 1 / 1 + / \ | | .---+ .-+ + + / \ .---+---. .--+--. | '--- 2 | '-- 2 / \ 2 + + + | | | | ---+ ---+ + + / \ / \ .-+-. .-+-. .+. .+. | .--- 3 | .-- 3 \ / 3 + / \ / \ | | | | | | | | '---+ '-+ + + 1 2 3 4 1 2 3 4 1 2 3 4 '--- 4 '-- 4 \ 4 +``` + + + + + ## Mermaid Diagrams +Hugo currently does not provide default templates for Mermaid diagrams. But you can easily add your own. One way to do it would be to create ` layouts/_default/_markup/render-codeblock-mermaid.html`: + + +```go-html-template +<div class="mermaid"> + {{- .Inner | safeHTML }} +</div> +{{ .Page.Store.Set "hasMermaid" true }} +``` + +And then include this snippet at the bottom of the content template (below `.Content`): + +```go-html-template +{{ if .Page.Store.Get "hasMermaid" }} + <script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script> + <script> + mermaid.initialize({ startOnLoad: true }); + </script> +{{ end }} +``` + +With that you can use the `mermaid` language in Markdown code blocks: + ```mermaid sequenceDiagram participant Alice diff --git a/docs/content/en/hosting-and-deployment/deployment-with-nanobox.md b/docs/content/en/hosting-and-deployment/deployment-with-nanobox.md deleted file mode 100644 index 1ab77c401..000000000 --- a/docs/content/en/hosting-and-deployment/deployment-with-nanobox.md +++ /dev/null @@ -1,249 +0,0 @@ ---- -title: Host-Agnostic Deploys with Nanobox -linktitle: Host-Agnostic Deploys with Nanobox -description: Easily deploy Hugo to AWS, DigitalOcean, Google, Azure, and more... -date: 2017-08-24 -publishdate: 2017-08-24 -lastmod: 2017-08-24 -categories: [hosting and deployment] -keywords: [nanobox,deployment,hosting,aws,digitalocean,azure,google,linode] -authors: [Steve Domino] -menu: - docs: - parent: "hosting-and-deployment" - weight: 05 -weight: 05 -sections_weight: 05 -draft: false -aliases: [/tutorials/deployment-with-nanobox/] -toc: true ---- - -![hugo with nanobox](/images/hosting-and-deployment/deployment-with-nanobox/hugo-with-nanobox.png) - -Nanobox provides an entire end-to-end workflow for developing and deploying applications. Using Nanobox to deploy also means you'll use it to develop your application. - -{{% note %}} -If you're already using Nanobox and just need deployment instructions, you can skip to [Deploying Hugo with Nanobox](#deploying-hugo-with-nanobox) -{{% /note %}} - - -## What You'll Need - -With Nanobox you don't need to worry about having Go or Hugo installed. They'll be installed as part of the development environment created for you. - -To get started you'll just need the following three items: - -* [A Nanobox Account](https://nanobox.io) - Signup is free -* [Nanobox Desktop](https://dashboard.nanobox.io/download) - The free desktop development tool -* An account with a hosting provider such as: - - [AWS](https://docs.nanobox.io/providers/hosting-accounts/aws/) - - [Google](https://docs.nanobox.io/providers/hosting-accounts/gcp/) - - [Azure](https://docs.nanobox.io/providers/hosting-accounts/azure/) - - [DigitalOcean](https://docs.nanobox.io/providers/hosting-accounts/digitalocean/) - - [Linode](https://docs.nanobox.io/providers/hosting-accounts/linode/) - - [More...](https://docs.nanobox.io/providers/hosting-accounts/) - - [Roll Your Own](https://docs.nanobox.io/providers/create/) - -### Before You Begin - -There are a few things to get out of the way before diving into the guide. To deploy, you'll need to make sure you have connected a host account to your Nanobox account, and launched a new application. - -#### Connect a Host Account - -Nanobox lets you choose where to host your application (AWS, DigitalOcean, Google, Azure, etc.). In the [Hosting Accounts](https://dashboard.nanobox.io/provider_accounts) section of your Nanobox dashboard [link your Nanobox account with your host](https://docs.nanobox.io/providers/hosting-accounts/). - -#### Launch a New Application on Nanobox - -[Launching a new app on Nanobox](https://docs.nanobox.io/workflow/launch-app/) is very simple. Navigate to [Launch New App](https://dashboard.nanobox.io/apps/new) in the dashboard, and follow the steps there. You'll be asked to name your app, and to select a host and region. - -With those out of the way you're ready to get started! - - -## Getting Started - -{{% note %}} -If you already have a functioning Hugo app, you can skip to [Configure Hugo to run with Nanobox](#configure-hugo-to-run-with-nanobox) -{{% /note %}} - -To get started, all you'll need is an empty project directory. Create a directory wherever you want your application to live and `cd` into it: - -`mkdir path/to/project && cd path/to/project` - -### Configure Hugo to run with Nanobox - -Nanobox uses a simple config file known as a [boxfile.yml](https://docs.nanobox.io/boxfile/) to describe your application's infrastructure. In the root of your project add the following `boxfile.yml`: - -{{< code file="boxfile.yml" >}} -run.config: - - # use the static engine - engine: static - engine.config: - - # tell the engine where to serve static assets from - rel_dir: public - - # enable file watching for live reload - fs_watch: true - - # install hugo - extra_steps: - - bash ./install.sh - -deploy.config: - - # generate site on deploy - extra_steps: - - hugo - -{{< /code >}} - -{{% note %}} -If you already have a functioning Hugo app, after adding the boxfile, you can skip to [Deploying Hugo with Nanobox](#deploying-hugo-with-nanobox). -{{% /note %}} - -### Installing Hugo - -Nanobox uses Docker to create instant, isolated, development environments. Because of this, you'll need to make sure that during development you have Hugo available. - -Do this by adding a custom install script at the root of your project that will install Hugo automatically for you: - -{{< code file="install.sh" >}} - -#!/bin/bash - -if [[ ! -f /data/bin/hugo ]]; then - cd /tmp - wget https://github.com/gohugoio/hugo/releases/download/v0.31.1/hugo_0.31.1_Linux-64bit.tar.gz - tar -xzf hugo_0.31.1_Linux-64bit.tar.gz - mv hugo /data/bin/hugo - cd - - rm -rf /tmp/* -fi - -{{< /code >}} - -{{% note %}} -If the install script fails during `nanobox run` you may need to make it executable with `chmod +x install.sh` -{{% /note %}} -{{% note %}} -Make sure to check the version of Hugo you have installed and update the install script to match. -{{% /note %}} - -### Generating a New Hugo App - -You'll generate your new application from inside the Nanobox VM (this is why you don't need to worry about having Go or Hugo installed). - -Run the following command to drop into a Nanobox console (inside the VM) where your codebase is mounted: - -``` -nanobox run -``` - -![nanobox run](/images/hosting-and-deployment/deployment-with-nanobox/nanobox-run.png) - -Once inside the console use the following steps to create a new Hugo application: - -``` -# cd into the /tmp dir to create an app -cd /tmp - -# generate the hugo app -hugo new site app - -# cd back into the /app dir -cd - - -# copy the generated app into the project -shopt -s dotglob -cp -a /tmp/app/* . -``` - -### Install a theme - -`cd` into the `themes` directory and clone the `nanobox-hugo-theme` repo: - -``` -cd themes -git clone https://github.com/sdomino/nanobox-hugo-theme -``` - -To use the theme *either* copy the entire `config.toml` that comes with the theme, or just add the theme to your existing `config.toml` - -``` -# copy the config.toml that comes with the theme -cp ./themes/nanobox-hugo-theme/config.toml config.toml - -# or, add it to your existing config.toml -theme = "nanobox-hugo-theme" -``` - -{{% note %}} -It is not intended that you use the `nanobox-hugo-theme` as your actual theme. It's simply a theme to start with and should be replaced. -{{% /note %}} - -### View Your App - -To view your application simply run the following command from a Nanobox console: - -``` -hugo server --bind="0.0.0.0" --baseUrl=$APP_IP -``` - -![hugo server](/images/hosting-and-deployment/deployment-with-nanobox/hugo-server.png) - -With that you should be able to visit your app at the given IP:1313 address - -{{% note %}} -You can [add a custom DNS alias](https://docs.nanobox.io/cli/dns/#add) to make it easier to access your app. Run `nanobox dns add local hugo.dev`. After starting your server, visit your app at [hugo.dev:1313](http://hugo.dev:1313) -{{% /note %}} - -### Develop, Develop, Develop - -{{% note %}} -IMPORTANT: One issue we are aware of, and actively investigating, is livereload. Currently, livereload does not work when developing Hugo applications with Nanobox. -{{% /note %}} - -With Hugo installed you're ready to go. Develop Hugo like you would normally (using all the generators, etc.). Once your app is ready to deploy, run `hugo` to generate your static assets and get ready to deploy! - - -## Deploying Hugo with Nanobox - -{{% note %}} -If you haven't already, make sure to [connect a hosting account](#connect-a-host-account) to your Nanobox account, and [launch a new application](#launch-a-new-application-on-nanobox) in the Dashboard. -{{% /note %}} - -To deploy your application to Nanobox you simply need to [link your local codebase](https://docs.nanobox.io/workflow/deploy-code/#add-your-live-app-as-a-remote) to an application you've created on Nanobox. That is done with the following command: - -``` -nanobox remote add <your-app-name> -``` - -{{% note %}} -You may be prompted to login using your ***Nanobox credentials*** at this time -{{% /note %}} - -### Stage Your Application (optional) - -Nanobox gives you the ability to [simulate your production environment locally](https://docs.nanobox.io/workflow/deploy-code/#preview-locally). While staging is optional it's always recommended, so there's no reason not to! - -To stage your app simply run: - -``` -nanobox deploy dry-run -``` - -Now visit your application with the IP address provided. - -![nanobox deploy dry-run](/images/hosting-and-deployment/deployment-with-nanobox/nanobox-deploy-dry-run.png) - -### Deploy Your Application - -Once everything checks out and you're [ready to deploy](https://docs.nanobox.io/workflow/deploy-code/#deploy-to-production), simply run: - -``` -nanobox deploy -``` - -Within minutes you're Hugo app will be deployed to your host and humming along smoothly. That's it! diff --git a/docs/content/en/hosting-and-deployment/hosting-on-github.md b/docs/content/en/hosting-and-deployment/hosting-on-github.md index 675a696d3..ae30ce44a 100644 --- a/docs/content/en/hosting-and-deployment/hosting-on-github.md +++ b/docs/content/en/hosting-and-deployment/hosting-on-github.md @@ -34,14 +34,16 @@ There are two types of GitHub Pages: Please refer to the [GitHub Pages documentation][ghorgs] to decide which type of site you would like to create as it will determine which of the below methods to use. +## Branches for GitHub Actions + +The GitHub Actions used in these instructions pull source content from the `main` branch and then commit the generated content to the `gh-pages` branch. This applies regardless of what type of GitHub Pages you are using. This is a clean setup as your Hugo files are stored in one branch and your generated files are published into a separate branch. + ## GitHub User or Organization Pages As mentioned in the [GitHub Pages documentation][ghorgs], you can host a user/organization page in addition to project pages. Here are the key differences in GitHub Pages websites for Users and Organizations: -1. You must use a `<USERNAME>.github.io` to host your **generated** content -2. Content from the `main` branch will be used to publish your GitHub Pages site - -This is a much simpler setup as your Hugo files and generated content are published into two different repositories. +1. You must create a repository named `<USERNAME>.github.io` or `<ORGANIZATION>.github.io` to host your pages +2. By default, content from the `main` branch is used to publish GitHub Pages - rather than the `gh-pages` branch which is the default for project sites. However, the GitHub Actions in these instructions publish to the `gh-pages` branch. Therefore, if you are publishing Github pages for a user or organization, you will need to change the publishing branch to `gh-pages`. See the instructions later in this document. ## Build Hugo With GitHub Action diff --git a/docs/content/en/hugo-pipes/introduction.md b/docs/content/en/hugo-pipes/introduction.md index babf9cdb8..83d64d1d3 100755 --- a/docs/content/en/hugo-pipes/introduction.md +++ b/docs/content/en/hugo-pipes/introduction.md @@ -18,6 +18,23 @@ toc: true aliases: [/assets/] --- +## Find Resources in /assets + +This is about the global Resources mounted inside `/assets`. For the `.Page` scoped Resources, see [Page Resources](/content-management/page-resources/). + +Note that you can mount any directory into Hugo's virtual `assets` folder using the [Mount Configuration](/hugo-modules/configuration/#module-config-mounts). + +| Function | Description | +| ------------- | ------------- | +| `resources.Get` | Get locates the filename given in Hugo's assets filesystem and creates a `Resource` object that can be used for further transformations. See [Get Resource with resources.Get and resources.GetRemote](#get-resource-with-resourcesget-and-resourcesgetremote). | +| `resources.GetRemote` | Same as `Get`, but it accepts remote URLs. See [Get Resource with resources.Get and resources.GetRemote](#get-resource-with-resourcesget-and-resourcesgetremote).| +| `resources.GetMatch` | `GetMatch` finds the first Resource matching the given pattern, or nil if none found. See Match for a more complete explanation about the rules used. | +| `resources.Match` | `Match` gets all resources matching the given base path prefix, e.g "*.png" will match all png files. The "*" does not match path delimiters (/), so if you organize your resources in sub-folders, you need to be explicit about it, e.g.: "images/*.png". To match any PNG image anywhere in the bundle you can do "\*\*.png", and to match all PNG images below the images folder, use "images/\*\*.jpg". The matching is case insensitive. Match matches by using the files name with path relative to the file system root with Unix style slashes (/) and no leading slash, e.g. "images/logo.png". See https://github.com/gobwas/glob for the full rules set.| + + +See the [GoDoc Page](https://pkg.go.dev/github.com/gohugoio/hugo@v0.93.1/tpl/resources) for the `resources` package for an up to date overview of all template functions in this namespace. + + ## Get Resource with resources.Get and resources.GetRemote In order to process an asset with Hugo Pipes, it must be retrieved as a `Resource` using `resources.Get` or `resources.GetRemote`. diff --git a/docs/content/en/news/0.15-relnotes/index.md b/docs/content/en/news/0.15-relnotes/index.md index 5053e3fb2..cd268eaa6 100644 --- a/docs/content/en/news/0.15-relnotes/index.md +++ b/docs/content/en/news/0.15-relnotes/index.md @@ -80,7 +80,7 @@ Huge thanks to all who participated in this release. A special thanks to [@bep]( ## Bugfixes - Fix data races in page sorting and page reversal. These operations are now also cached. [#1293](https://github.com/spf13/hugo/issues/1293) - `page.HasMenuCurrent()` and `node.HasMenuCurrent()` now work correctly in multi-level nested menus. -- Support `Fish and Chips` style section titles. Previously, this would end up as `Fish And Chips`. Now, the first character is made toupper, but the rest are preserved as-is. [#1176](https://github.com/spf13/hugo/issues/1176) +- Support `Fish and Chips` style section titles. Previously, this would end up as `Fish And Chips`. Now, the first character is made to upper, but the rest are preserved as-is. [#1176](https://github.com/spf13/hugo/issues/1176) - Hugo now removes superfluous p-tags around shortcodes. [#1148](https://github.com/spf13/hugo/issues/1148) ## Notices diff --git a/docs/content/en/news/0.20-relnotes/index.md b/docs/content/en/news/0.20-relnotes/index.md index 75e944a6c..27e4d48f7 100644 --- a/docs/content/en/news/0.20-relnotes/index.md +++ b/docs/content/en/news/0.20-relnotes/index.md @@ -42,7 +42,7 @@ Worth mentioning is also the ongoing work that [@rdwatters](//github.com/rdwatte * Hugo `0.20` is built with Go 1.8.1. * Add `.Site.Params.mainSections` that defaults to the section with the most pages. Plan is to get themes to use this instead of the hardcoded `blog` in `where` clauses. [#3206](//github.com/gohugoio/hugo/issues/3206) * File extension is now configurable. [#320](//github.com/gohugoio/hugo/issues/320) -* Impove `markdownify` template function performance. [#3292](//github.com/gohugoio/hugo/issues/3292) +* Improve `markdownify` template function performance. [#3292](//github.com/gohugoio/hugo/issues/3292) * Add taxonomy terms’ pages to `.Data.Pages` [#2826](//github.com/gohugoio/hugo/issues/2826) * Change `RSS` description from full `.Content` to `.Summary`. * Ignore “.” dirs in `hugo --cleanDestinationDir` [#3202](//github.com/gohugoio/hugo/issues/3202) diff --git a/docs/content/en/news/0.22-relnotes/index.md b/docs/content/en/news/0.22-relnotes/index.md index 8a9e8d5f5..fefb501f6 100644 --- a/docs/content/en/news/0.22-relnotes/index.md +++ b/docs/content/en/news/0.22-relnotes/index.md @@ -74,7 +74,7 @@ Also, considerable work has been put into writing automated benchmark tests for ### Docs * Rewrite “Archetypes” article [@davidturnbull](https://github.com/davidturnbull) [#3543](https://github.com/gohugoio/hugo/pull/3543/) -* Remove Unmaintaned Frontends from Tools. [f41f7282](https://github.com/gohugoio/hugo/commit/f41f72822251c9a31031fd5b3dda585c57c8b028) [@onedrawingperday](https://github.com/onedrawingperday) +* Remove Unmaintained Frontends from Tools. [f41f7282](https://github.com/gohugoio/hugo/commit/f41f72822251c9a31031fd5b3dda585c57c8b028) [@onedrawingperday](https://github.com/onedrawingperday) ## Fixes diff --git a/docs/content/en/news/0.46-relnotes/index.md b/docs/content/en/news/0.46-relnotes/index.md index ef0df2427..65c2f1036 100644 --- a/docs/content/en/news/0.46-relnotes/index.md +++ b/docs/content/en/news/0.46-relnotes/index.md @@ -38,7 +38,7 @@ Hugo now has: ## Enhancements * Add `templates.Exists` template function. This can be used to check if a template, e.g. a partial, exists in the project or any of the themes in use. [0ba19c57](https://github.com/gohugoio/hugo/commit/0ba19c57f180c33b41c64335ea1d1c89335d34c0) [@bep](https://github.com/bep) [#5010](https://github.com/gohugoio/hugo/issues/5010) -* Remove superflous loop [0afa2897](https://github.com/gohugoio/hugo/commit/0afa2897a0cf90f4348929ef432202efddc183a0) [@bep](https://github.com/bep) +* Remove superfluous loop [0afa2897](https://github.com/gohugoio/hugo/commit/0afa2897a0cf90f4348929ef432202efddc183a0) [@bep](https://github.com/bep) * Update Chroma [b5d13ca1](https://github.com/gohugoio/hugo/commit/b5d13ca16bf106c1bc29c2a5295cd231d1bf13fd) [@bep](https://github.com/bep) [#5019](https://github.com/gohugoio/hugo/issues/5019) * Make resources fetched via `resources.Get` and similar language agnostic [6b02f5c0](https://github.com/gohugoio/hugo/commit/6b02f5c0f4e0ba1730aebc5a590a111548233bd5) [@bep](https://github.com/bep) [#5017](https://github.com/gohugoio/hugo/issues/5017) * Improve SCSS project vs themes import resolution [f219ac09](https://github.com/gohugoio/hugo/commit/f219ac09f6b7e26d84599401512233d77c1bdb4c) [@bep](https://github.com/bep) [#5008](https://github.com/gohugoio/hugo/issues/5008) |